Errors

Every error has the same shape, whatever the endpoint:

{
  "error": {
    "code": "network_unavailable",
    "message": "net_ng_a is not accepting purchases right now.",
    "retryable": true,
    "request_id": "req_7Cv5Gm2TzP8h",
    "details": {
      "network": {
        "id": "net_ng_a",
        "status": "unavailable",
        "status_message": "The network is not confirming purchases. We are working with it.",
        "status_updated_at": "2026-10-12T09:02:00Z"
      }
    }
  }
}

Field	Use it for
code	Your logic. Codes are stable within a version.
message	Your logs. It is written for people and may change, so never parse it.
param	The request field at fault, when there is one.
retryable	Whether the same request can succeed later.
request_id	Quoting to your technical contact. It also comes back in the Aura-Request-Id header.
details	Extra facts, such as the existing purchase on a reference_conflict or the network’s status.

Error codes

Code	HTTP	Retryable	Meaning
invalid_request	400	No	A field is missing, malformed or out of range. param names it.
invalid_phone_number	400	No	The number is not a valid E.164 mobile number.
invalid_api_key	401	No	The key is missing, wrong, revoked, or for the other environment.
insufficient_balance	402	No, until you top up	Your available balance does not cover the price.
ip_not_allowed	403	No	The request came from an address outside your allowlist.
not_found	404	No	The purchase, bundle, network or statement does not exist on your account.
reference_conflict	409	No	The reference belongs to a different purchase. details.purchase_id names it.
bundle_unavailable	422	No	The bundle is not on sale now. Refresh your catalogue.
network_mismatch	422	No	The number is on a different network from the network_id you sent. details.detected_network_id names the right one.
unsupported_network	422	No	The number is on a network your account does not cover.
rate_limited	429	Yes	Too many requests. Wait for Retry-After seconds.
internal_error	500	Yes	Aura could not complete the request. Retry with backoff and the same reference.
network_unavailable	503	Yes	The network is not accepting purchases. details carries its live status.

New codes may be added within v1. Handle an unknown code by its HTTP status and retryable flag.

Failure codes on purchases

A purchase that was accepted but not delivered ends as failed, with a failure.code. These are not HTTP errors: they arrive on the purchase and in the purchase.failed webhook. They are listed in Transaction lifecycle.