Reference

Errors

Every error has a stable code, an HTTP status and, when it makes sense, retry guidance.

Shape

Codes follow XXX-###: a domain prefix and a number. When a retry could succeed, the body says so with retryable and, if known, retryAfterSeconds (also sent as a Retry-After header).

402 Payment Required

{
  "success": false,
  "error": {
    "code": "PAY-101",
    "message": "Subscriber balance is insufficient",
    "retryable": true,
    "retryAfterSeconds": 14400
  }
}

Common codes

Code	HTTP	Meaning
`ATH-002`	401	Token missing, malformed or not recognised.
`AUZ-002`	403	Your application lacks the capability for this route.
`VAL-001`	400	A required field is missing.
`VAL-002`	400	A field has an invalid format or value.
`VAL-006`	400	Unknown property, for example amount or msisdn in hosted mode.
`SEC-001`	429	Rate limit reached.
`CAT-102`	404	Offer not found.
`CAT-103`	422	Offer is not active.
`CAT-104`	403	Your application is not authorised for this offer.
`CAT-109`	409	This one-time item is already owned.
`PAY-101`	402	Subscriber balance is insufficient. Retryable.
`PAY-103`	402	Charge declined by the operator. Retryable.
`PAY-104`	409	A request with this idempotency key is still in progress. Retry shortly.
`PAY-105`	409	Idempotency key reused with a different payload.
`SBR-102`	400	Mobile number is invalid.
`SBR-104`	422	This mobile operator is not supported.
`RSK-101`	403	The subscriber has opted out of carrier billing.
`SUB-101`	404	Subscription not found.
`SUB-104`	409	Subscription is already canceled.
`SUB-105`	409	No scheduled cancellation to withdraw.
`SUB-108`	409	Trial already used for this product.

Handling them well

Branch on the code, not the message. Messages can be reworded.
Retry only when retryable, and after the suggested delay.
On PAY-104, wait and retry with the same Idempotency-Key.