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

# Conventions

> Request format, identifiers and errors shared by every endpoint

Conventions that apply to every request.

## Request format

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

## Response format

JSON with **snake\_case** keys. Timestamps are ISO 8601 in UTC
(`2026-11-16T03:00:00Z`); calendar dates are `YYYY-MM-DD`.

Ignore keys you do not recognise. We add fields without notice and record them
in the [changelog](https://docs.esimmu.com/changelog.md); we do not remove or rename one without notice.

## Identifiers

| Identifier | Who sets it | What it is |
| - | - | - |
| `external_order_id` | **You** | Your own reference for an order. Unique within your account |
| `option_id` | Us | A product, from the product list we send you |
| `topup_id` | Us | One eSIM. Every per-eSIM endpoint and webhook is keyed on it |

`external_order_id` is 1 to 64 characters of letters, digits, `-` and `_`. It
only has to be unique among your own orders. It is also what makes ordering
safe to retry: see [Retrying an order](https://docs.esimmu.com/endpoints/create-order.md#retrying-an-order).

## Errors

Every error is JSON, in one of three shapes depending on the status:

| Status | Shape | When |
| - | - | - |
| `400` | `{"error": "..."}` | The body is not valid JSON. The message is the parser's and its wording is not stable |
| `401` | `{"error": {"code": "unauthorized", "message": "..."}}` | Signing failed; see [Authentication](https://docs.esimmu.com/authentication/overview.md#errors) |
| `404` | `{"errors": ["eSIM not found"]}` | No eSIM with that `topup_id` on your account |
| `422` | `{"errors": ["..."]}` | The request is well-formed but cannot be carried out; the message says why |

`5xx` responses are not guaranteed to be JSON. Do not parse them; retry later.

A `422` caused by our eSIM provider carries a generic message,
`eSIM provider request failed. Please retry later.` For an order, retry with the
same `external_order_id`.

Each endpoint lists its own errors under its Errors section, for example
[Create an order](https://docs.esimmu.com/endpoints/create-order.md#errors).

## Rate limits

[List products](https://docs.esimmu.com/endpoints/list-products.md) allows **10 requests per minute** per
access key; it returns the whole catalogue and is meant to be fetched daily.
Going over returns `429` with a `Retry-After` header in seconds and
`{"errors": ["Too many requests. Please try again shortly."]}`.


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