Error codes

Every error uses the same envelope: an HTTP status plus a typed body. Switch on error.type to handle them programmatically.

{
  "error": {
    "type": "InsufficientFundsError",
    "message": "Not enough balance to send."
  }
}

Reference

Status	Type	Meaning
422	ValidationError	Missing or malformed request body.
422	InvalidRecipientError	recipient is not a valid phone or email.
401	HTTPException	Missing, invalid, or revoked API key.
404	HTTPException	otp_id not found, or not on your company.
403	GeoBlockedError	The recipient’s country is blocked.
403	IpReputationBlockedError	The declared client_ip is a known abuse source (see send).
402	InsufficientFundsError	Not enough balance to send.
429	RateLimitExceededError	Too many requests for this recipient.
409	ResendNotAllowedError	No further channel to fall back to.
429	ResendCooldownError	Resend attempted within the cooldown window.
422	InvalidIdempotencyKeyError	The idempotency-key header is longer than 128 characters.

Handling errors

• 401 means the key is wrong or revoked. Check Authentication.
• 402 and 403 are account, destination, or client-IP policy limits, not code bugs; surface a clear message and stop retrying.
• 429 is rate limiting or a resend cooldown; back off and try again later. A message of Rate limit exceeded: client_ip means your requests are not passing the end user’s IP; add client_ip to send for the normal limits.
• 409 on resend means the fallback chain is exhausted; start a new send if appropriate.
• 422 is a validation problem in the request: fix the body (or the idempotency-key header) and retry. Retrying the same request unchanged will fail the same way.