API documentation

Errors

The uniform error shape, the stable error codes, and when to retry.

Every error comes with a fitting HTTP status and the same shape. Branch on code only: message wording can change.

Error shape

{
  "error": {
    "code": "validation_failed",
    "message": "The request is invalid. Check the parameters and try again.",
    "message_ar": "الطلب غير صالح. تحقق من المعطيات وأعد المحاولة.",
    "detail": "invalid phone number"
  }
}

Error fields

error.codestringrequired
A stable code from the table below.
error.messagestringrequired
English description, safe to show to users.
error.message_arstringrequired
The same description in Arabic.
error.detailstring
Optional technical hint in English, such as the failing field. For debugging only.

Error codes

HTTP	code	Meaning
`400`	`validation_failed`	Invalid input: phone, JSON, unknown field, or a malformed `Idempotency-Key`
`401`	`unauthenticated`	Missing, invalid or revoked API key
`402`	`insufficient_balance`	Balance does not cover the first channel. Nothing was sent
`402`	`spend_cap_reached`	The project's monthly spending limit is reached
`403`	`forbidden`	Your server's IP is not in the project allowlist
`403`	`test_number_required`	Test keys only send to registered test numbers
`404`	`not_found`	Not found, or it belongs to another project or mode (test/live)
`409`	`idempotency_conflict`	Key reused with a different request, or the first one is still running
`429`	`rate_limited`	Too many requests for this phone or IP. Comes with `Retry-After: 60`
`500`	`internal_error`	Something went wrong on our side
`502`	`delivery_failed`	Every channel failed; everything was refunded
`503`	`no_channel_available`	No configured and priced channel for this number

When to retry

429: wait for Retry-After (seconds), then retry.
500 or a network error: retry with the same Idempotency-Key, so the code is never sent twice. See Idempotency.
502 delivery_failed and 503: an immediate retry will not help. Offer the user another option or try later.
400, 401, 402, 403, 404: fix the request or settings first.