Code: A numeric or HTTP-based identifier that categorizes the error.
Reason: A detailed explanation of the error, including additional context when applicable.
🔁 Migrating from Partner API V1? On V1, most order failures return a generic server error (HTTP 500), and insufficient balance returns HTTP 402 without a code.
| Retry class | What your client should do | Codes |
|---|---|---|
| Retry with backoff | The condition is temporary and the 83same request can succeed later. Retry with increasing delays. | 13, 33, 53, 429, 500, 502, 503, 504 |
| Fix the request | Change the payload or your account state before retrying. Resending the same request will fail again. | 11, 14, 23, 34, 43, 73, 89, 401, 404 |
| Check status first | Your earlier request may have succeeded. Look up the order before any retry. | 83 |
| Contact support | You can't resolve this yourself. Contact support. | 88, and any 53 or 5xx error that persists after retries |
⚠️ Code 83: your previous request may have succeeded. V2 rejects an order, async order, top-up or future-order request with the same parameters as one sent in the previous second."
| Code | HTTP | Reason | Client response | Retry class |
|---|---|---|---|---|
| 11 | 422 | Insufficient Airalo Credit: {additional} | Top up your Airalo credit balance, then resubmit. | Fix the request |
| 13 | 422 | The requested operator is currently undergoing maintenance. Please try again later. | Wait, then retry with backoff. | Retry with backoff |
| 14 | 422 | Invalid checksum: {additional} | Your airalo-signature header doesn't match resending the request. Recompute it with your current client secret, then resend. | Fix the request |
| 23 | 422 | The requested top-up has been disabled by the operator. {additional} | Don't retry this top-up. Offer the customer a different package. | Fix the request |
| 33 | 422 | Insufficient stock of eSIMs remaining: {additional}. Please try your request again later. | Retry later with backoff. | Retry with backoff |
| 34 | 422 | The requested eSIM package is invalid or it is currently out of stock. | Refresh your package list from Get packages and resend with a current package_id. | Fix the request |
| 43 | 422 | Bad request. {additional} Please check your input and try again. | Correct the input described in the message, then resend. | Fix the request |
| 53 | 422 | Something unexpected happened. We're working to resolve the issue. Please try again later. | Retry later with backoff. Contact support if it persists. | Retry with backoff |
| 73 | 422 | The eSIM with iccid {additional} has been recycled. It can no longer be used or topped up. | Don't retry with this ICCID. The customer needs a new eSIM. | Fix the request |
| 83 | 422 | Request throttled. You have already placed an identical order | Check the order status before retrying; do not resend the same payload. | Check status first |
| Code | HTTP | Reason | Client response | Retry class |
|---|---|---|---|---|
| 401 | 401 | Authentication failed. This could be due to an expired token, please generate a new token. If the issue persists, verify your client_id and client_secret are correct. | Request a new access token and retry. If it still fails, check your client_id and client_secret. | Fix the request |
| 404 | 404 | Not found, for example an invalid or unknown package_slug. | Check the identifier in the request path. | Fix the request |
| 429 | 429 | Too Many Attempts (rate limit) | Slow down and retry with exponential backoff. Stay within the rate limit documented for each endpoint. | Retry with backoff |
| 88 | 403 | Ordering has been disabled for your company. Read endpoints remain available. Please contact support to reset your API credentials and restore ordering. | Contact support to reset your API credentials and resume orders | Contact support |
| 89 | 403 | Your IP address is not permitted to access the Partner API. Add it to your API IP allowlist in the Partner Platform, or contact your account manager.. | Add the calling IP address to your allow list, then retry. | Fix the request |
| HTTP Code | Reason | Client response | Retry class |
|---|---|---|---|
| 500, 502, 503, 504 | Internal Server Error | Retry with backoff. If it persists, check the status page or contact support. | Retry with backoff |