Errors

This page covers the global error model: the shape of every failure response, the HTTP status codes the API uses, and the message codes that can appear regardless of endpoint. For carrier-originated failures (INSUFFICIENT_FUNDS, BLACKLISTED, etc.), see Carrier errors.

Failure envelope

Failures use the same envelope as successful responses, with status: "FAIL" and a machine-readable message. payload is omitted or null.

{
  "status": "FAIL",
  "message": "BAD_REQUEST",
  "status_code": 400,
  "payload": null
}

HTTP status codes

HTTP status	Meaning
200	The request reached the API. Inspect the JSON status field — it may still be "FAIL".
400	Malformed request body or missing required fields.
401	Missing, invalid, or inactive API key.
403	Source IP not allowlisted, or the merchant has no integration for the requested service/country.
404	Resource not found (for example, an unknown subscription_id).
500	Unexpected server error. Safe to retry with exponential backoff.

A 200 response always contains a JSON envelope; clients must branch on status to detect business-logic failures. See Conventions → HTTP 200 with status: "FAIL".

Global message codes

These codes can be returned by any endpoint:

message	When
UNAUTHORIZED	API key missing, invalid, or inactive; or source IP not allowlisted.
BAD_REQUEST	Required fields missing, or schema validation failed.
METHOD_NOT_ALLOWED	Wrong HTTP method. All endpoints are POST.
MERCHANT_SERVICE_NOT_CONFIGURED	The merchant has no integration provisioned for that service_code + country_code combination.
ERROR	Unexpected server-side failure. Safe to retry with backoff.

Endpoint-specific failures (for example SUBSCRIPTION_NOT_FOUND for the status endpoint) are documented on their respective pages.

Carrier-originated failures

A separate class of failures bubbles up from the underlying mobile carrier and is exposed via the message field. These are listed in Carrier errors. Carrier errors generally return HTTP 200 with status: "FAIL" because the request itself was valid — the carrier refused.