> ## Documentation Index
> Fetch the complete documentation index at: https://docs.esimstory.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions

> Request format, errors and rate limits shared by every endpoint

Conventions that apply to every request, and the limits you share across them.

## Request format

* `Content-Type: application/json`
* The three signature headers on every call — see
  [Authentication](https://docs.esimstory.com/authentication/overview.md)
* A timestamp within 5 minutes of our clock

## Response format

JSON with snake\_case keys. Errors come in one of two shapes, and which one you
get depends on the status:

| Status | Shape |
| - | - |
| `401`, `404` — and `422` from the refund endpoints | `{"error": {"code": "...", "message": "..."}}` |
| `422` from Create an order, `429` | `{"errors": ["...", "..."]}` |
| `400` | `{"error": "..."}` — raw parser message, wording not stable |
| `5xx` | Not guaranteed to be JSON. Do not parse |

Each status is documented under the endpoint's own Errors section — for
example [Create an order](https://docs.esimstory.com/endpoints/create-order.md#errors).

## Rate limits

**300 requests per 5 minutes**, counted by source IP across all endpoints.
Contact support if your integration needs a higher ceiling.

Some endpoints carry a second, tighter limit, counted against your access key
rather than your IP. Both limits apply to them.

| Endpoint | Limit | Why |
| - | - | - |
| [List products](https://docs.esimstory.com/endpoints/list-products.md) | **10 requests per minute** | The response is the whole catalogue. Fetch it daily and cache it |
| [Get eSIM status](https://docs.esimstory.com/endpoints/esim-status.md) | **60 requests per minute** | Every call reaches the upstream provider |
| [Request a refund](https://docs.esimstory.com/endpoints/request-refund.md) and [Get a refund request](https://docs.esimstory.com/endpoints/get-refund.md) | **30 requests per minute**, shared | Opening a request starts a status check |

Going over returns `429 Too Many Requests` with a `Retry-After` header in
seconds:

```json theme={null}
{
  "errors": ["Too many requests. Please try again shortly."]
}
```

> [card] [List products](https://docs.esimstory.com/endpoints/list-products.md)
>
> The catalogue, at your price

> [card] [Create an order](https://docs.esimstory.com/endpoints/create-order.md)
>
> The endpoint and its errors


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.