Errors

Partner and merchant API errors use a consistent JSON envelope.

Error Envelope

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Field Meaning

Field	Type	Description
statusCode	number	HTTP status code returned by the endpoint.
message	string	Human-readable error message.
error	string	Standard HTTP error label, for example Bad Request or Conflict.

Common Status Codes

Code	Meaning
400	Invalid body, invalid path parameter, or missing/invalid required header (for example Idempotency-Key).
401	Missing or invalid authentication headers (X-API-Key, X-Timestamp, or X-Signature).
403	API key is not allowed for the caller IP or the operation is blocked by policy.
404	Requested resource was not found.
409	Idempotency conflict (same key with different payload) or request already in progress for that key.
422	Business rule rejection—for example partner limit checks, or account not enabled for the requested product line.
502	Upstream provider failure while processing the request.
503	Service temporarily unavailable.
504	Upstream provider timeout.
500	Unexpected server error.

Validation Notes

• Validation failures may return message: "Validation failed" when multiple field errors are present.
• If your account is not enabled for a product line, write endpoints return 422 with a message such as Partner is not entitled to purchase Airtime.
• Treat message as the primary troubleshooting signal and statusCode as the handling branch.
• Provider and server-side failures return sanitized messages; internal traces and raw upstream diagnostics are not exposed in API responses.

Callback Error Codes

When you subscribe to failure callbacks, context.errorCode may include:

Code	Meaning
PRODUCT_NOT_ENTITLED	Account is not enabled for the product line requested.