API docs

Errors

Every error comes with an HTTP status and a machine-readable code.

A failed request always answers with an error object. Branch on the code; use message only for logs and debugging, because its wording can change.

Response402 Payment Required

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits.",
    "balance": 40,
    "required": 70
  }
}

Error codes

HTTP	Code	Meaning
400	invalid_request	The request is wrong: a field is missing or invalid, or the body is not JSON.
401	invalid_api_key	The key is missing, unknown or revoked.
402	insufficient_credits	Not enough credits. Carries `balance` and `required`.
402	subscription_required	The trial ended or the base fee is not paid.
403	forbidden	You may not do this.
403	trial_recipient	A trial project can reach only its owner's confirmed phone and email.
404	not_found	Nothing with this id in this project, or the path is wrong.
410	verification_expired	The verification has expired.
422	unsupported_number	The number does not belong to a supported operator.
422	message_too_long	The SMS is over 5 parts, the email over 256 KB, or the request over 1 MB.
422	invalid_code	The verification code is wrong. Carries `attempts_remaining`.
429	rate_limited	Too many requests. See the `Retry-After` header.
429	recipient_rate_limited	Too many messages to this recipient.
429	max_attempts_reached	Too many wrong codes.
502	provider_failed	The operator did not accept the message. Credits were refunded. Carries `id`.
500	server_error	Something went wrong on our side.

How to handle them

Do not retry a 4xx with the same request. Fix the request or tell the user. The exception is 429: wait the Retry-After seconds and send again.
A 502 provider_failed can be retried: the credits are back. It may be a brief operator outage.
After a 500 server_error or a network failure you cannot know whether the message went out. Retry with an Idempotency-Key header so it is never sent twice.