Errors

The error envelope

Every error has the same shape. code is stable and meant for your code; message is for people; field names the request field when there is one.

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "to must be an E.164 Tanzanian number (+255...)",
    "field": "to"
  }
}

Common errors

• 400 invalid_request: a malformed request, or a missing or invalid X-Idempotency-Key.
• 401 unauthorized: a missing, invalid, expired or revoked API key.
• 403 insufficient_scope: the key lacks the operation's scope. Other 403 codes include sender_not_authorized, organization_not_verified, wallet_frozen and test_mode_not_allowed.
• 404 not_found: no such resource in your organization. Resources of other organizations answer the same way.
• 409 idempotency_conflict: the idempotency key was used with a different body.
• 422 validation_failed: a well-formed but invalid request, with field. Others: insufficient_funds, too_many_segments, consent_required, recipient_opted_out.
• 429 rate_limited: too many requests; wait for Retry-After seconds.
• 503: a dependency is busy or a read took too long (for example read_timeout); retry after Retry-After.

When to retry

Retry a 429 or a 503 after its Retry-After, and a network failure with the same idempotency key. Do not retry any other 4xx unchanged: fix the request first.