> For the complete documentation index, see [llms.txt](https://bump.sh/zim/doc/esim-api/llms.txt)

# Errors

Errors share a single body shape (`Error` schema): `{ "statusCode": 400, "message": "INSUFFICIENT_BALANCE", "error": "Bad Request" }`. For request validation errors `message` is an array of strings, one per invalid property.
Business-rule refusals a client is expected to handle return a stable code as `message`: match on equality, a code is never reworded. Among them: `INSUFFICIENT_BALANCE` (wallet does not cover the price), `PAYMENT_METHOD_NOT_ALLOWED` (your Account's billing does not allow ordering through the API, contact your account manager), `ALREADY_CANCELLED_ORDER`, `ALREADY_REFUNDED_ORDER`, `CANNOT_CANCEL_FULFILLED_ORDER`, `CANNOT_CANCEL_REPLACED_ORDER`, `ERROR_REFUNDING_ORDER`.


  * `400` - invalid request, or a business rule refused it (see `message`)
  * `401` - missing / invalid access token or `X-App-Identifier`
  * `403` - your role is not allowed to call this endpoint
  * `404` - the resource does not exist or does not belong to your Account
  * `409` - the resource is in a state that does not allow the operation
  * `500` - unexpected error, contact support with the request time


**Retries**: order creation endpoints are **not idempotent**. Do not blindly retry a timed-out or `5xx` purchase — first check `GET /orders` or `GET /subscriptions` to see whether it was created. Cancellation endpoints are safe to retry.


