1. REST API
Airalo Partner API
  • OVERVIEW
    • Introduction
    • Attribute descriptions
    • FAQ
    • Developer feedback
    • Quick start
      • Step 1: Request access token
      • Step 2: Get packages
      • Step 3: Submit order
      • Step 4: Get installation instructions
    • Guides
      • How to set up a brand for eSIMs Cloud link sharing
      • How to get the eSIMs Cloud sharing link through API
      • How to generate the QR code for an eSIM
      • eSIM installation methods for API Partners
  • REST API
    • Introduction
    • Go live checklist
    • Sandbox mode
    • Upgrade from v1 to v2 guide
    • Error handling
    • Rate limits
    • IP allowlist / whitelisting
    • Refund policy
    • Endpoints
      • Authenticate
        • Request access token
      • Browse packages
        • Get packages
      • Request refund
        • Request refund
      • Place order
        • Future orders
        • Submit order
        • Submit order async
        • eSIM voucher
      • Install eSIM
        • Get eSIM
        • Get installation instructions
      • Monitor usage
        • Get usage (data, text & voice)
      • Top up eSIM
        • Get top-up package list
        • Submit top-up order
      • Manage orders
        • Get order list
        • Get order
        • Cancel future orders
        • Future Orders
      • Manage eSIMs
        • Update eSIM brand
        • Get eSIMs list
        • Get eSIM package history
      • Compatible devices
        • [Deprecated] Get compatible device list
        • Get compatible device lite list
        • Check device compatibility
      • Notifications
        • Airalo webhooks opt-in and flow
        • Webhooks guide
        • Webhook definition
        • Notification: Low data
          • Opt in
          • Get notification details
          • Opt out
        • Notification: Credit limit
          • Opt in
          • Get notification details
          • Opt out
        • Notification: Async orders
          • Opt in
          • Get notification details
          • Opt out
        • Webhook simulator
      • Check balance
        • Get balance
      • Product Information
        • Get Product Information (PIB)
  • SDKs
    • Introduction
    • SDK vs. REST API
    • Technical notes
  • Whitelabel eSIM platform
    • Whitelabel eSIM platform integration guide
  1. REST API

Error handling

This page provides a comprehensive list of error codes that may be returned by the API during operation. Each error code is accompanied by a description of its meaning and potential causes, helping you to quickly identify and troubleshoot issues.
Error Code Structure
Code: A numeric or HTTP-based identifier that categorizes the error.
Reason: A detailed explanation of the error, including additional context when applicable.
Use this reference to understand why a particular request failed and to implement appropriate handling in your application, ensuring a robust and reliable integration with the API.
🔁 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.
How to respond, by 'Retry class'
Retry classWhat your client should doCodes
Retry with backoffThe condition is temporary and the 83same request can succeed later. Retry with increasing delays.13, 33, 53, 429, 500, 502, 503, 504
Fix the requestChange 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 firstYour earlier request may have succeeded. Look up the order before any retry.83
Contact supportYou can't resolve this yourself. Contact support.88, and any 53 or 5xx error that persists after retries

API Errors#

HTTP Code: 422 - Validation and Processing Errors
These errors occur when the request is well-formed but cannot be processed due to validation issues or other business rules.
⚠️ 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."
CodeHTTPReasonClient responseRetry class
11422Insufficient Airalo Credit: {additional}Top up your Airalo credit balance, then resubmit.Fix the request
13422The requested operator is currently undergoing maintenance. Please try again later.Wait, then retry with backoff.Retry with backoff
14422Invalid checksum: {additional}Your airalo-signature header doesn't match resending the request. Recompute it with your current client secret, then resend.Fix the request
23422The 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
33422Insufficient stock of eSIMs remaining: {additional}. Please try your request again later.Retry later with backoff.Retry with backoff
34422The 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
43422Bad request. {additional} Please check your input and try again.Correct the input described in the message, then resend.Fix the request
53422Something 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
73422The 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
83422Request throttled. You have already placed an identical orderCheck the order status before retrying; do not resend the same payload.Check status first

HTTP Code: 4xx#

CodeHTTPReasonClient responseRetry class
401401Authentication 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
404404Not found, for example an invalid or unknown package_slug.Check the identifier in the request path.Fix the request
429429Too Many Attempts (rate limit)Slow down and retry with exponential backoff. Stay within the rate limit documented for each endpoint.Retry with backoff
88403Ordering 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 ordersContact support
89403Your 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
Code 89 means the request came from an IP address that isn't on your allow list. Your credentials are still valid and nothing has been revoked. Add the address to your allow list and retry.

HTTP Codes: 5xx - Server Errors#

These errors are rare but may indicate a temporary outage or server issue. If a 5xx error persists, please check the status page or contact support.
HTTP CodeReasonClient responseRetry class
500, 502, 503, 504Internal Server ErrorRetry with backoff. If it persists, check the status page or contact support.Retry with backoff
Modified at 2026-10-26 16:28:19
Previous
Upgrade from v1 to v2 guide
Next
Rate limits
Built with