Errors

Every error has the same shape:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance. Required: €12.00, Available: €4.50"
  }
}

Match on code. The message is for people and can change.

Errors any endpoint can return

Status	Code	Meaning
401, 403	`AUTH_ERROR`	The API key was refused. See Authentication.
404	`NOT_FOUND`	The API is switched off. Every endpoint answers this, before your key is checked.
413	`PAYLOAD_TOO_LARGE`	The request body is larger than 100 KB.
429	`RATE_LIMITED`	Too many requests. Wait for the number of seconds in `Retry-After`.
500	`AUTH_ERROR`	We could not check your key. Try again.
500	`INTERNAL_ERROR`	Something failed on our side.

Errors per endpoint

Each endpoint lists its own codes in the API reference. The most common ones:

Status	Code	Meaning
400	`INVALID_JSON`	The body is not a JSON object.
400	`INSUFFICIENT_BALANCE`	Your wallet does not cover the order. Top up in the panel.
404	`PLAN_NOT_FOUND`, `ESIM_NOT_FOUND`	No plan or eSIM with that id for your account.
409	`ORDER_IN_PROGRESS`	The same order is still being processed. Do not retry. See Idempotency.
503	`PRICING_UNAVAILABLE`	Prices could not be read. Try again.
503	`PURCHASES_PAUSED`	Purchases are paused for a moment. Wait for `Retry-After`.

Retrying

A 429 or a 5xx can be retried, except the three below. Wait first, then send the same request again.
For purchases and top-ups, send an Idempotency-Key so a retry never charges twice. See Idempotency.
Other 4xx errors fail again until something changes, such as the request or your balance.