// errors

Errors

Every error returns the same envelope with a stable, machine-readable code. Branch on code, not the HTTP status alone - several scenarios can share one status.

{
  "status": "error",
  "statusCode": 402,
  "code": "INSUFFICIENT_CREDITS",
  "message": "Not enough credit balance to send this message.",
  "path": "/v1/messages",
  "data": null,
  "details": { "required": 2.8, "available": 1.2 }
}

The envelope fields:

Field	Description
status	Always `"error"`.
statusCode	Mirrors the HTTP status.
code	The stable discriminator to branch on.
message	Human-readable, safe to log; override for UX copy.
path	The request path that produced the error.
fieldErrors	Per-field messages on validation failures.
data	Always `null` on errors.

Error codes

Code	HTTP	Meaning
VALIDATION_ERROR	422	A field failed validation. See fieldErrors.
INVALID_API_KEY	401	The API key is missing or invalid.
API_KEY_REVOKED	401	The API key has been revoked.
API_KEY_SCOPE_DENIED	403	The key lacks the required scope for this call.
INSUFFICIENT_CREDITS	402	Not enough credit balance. Top up and retry.
DAILY_SPEND_CAP_EXCEEDED	403	This send would exceed your account's daily spend limit (resets 00:00 UTC).
PROBATION_LIMIT_EXCEEDED	403	New accounts can send a limited number of messages per rolling 24 hours for their first days after KYC approval. details has dailyLimit, used, remaining and endsAt. Nothing is charged.
RECIPIENT_NOT_VERIFIED	403	During the new-account period only numbers that confirmed an OTP for your account can be messaged. details has unverified (up to 5 numbers), unverifiedCount and endsAt. The whole request is rejected; nothing is sent or charged.
NO_VALID_RECIPIENTS	400	No recipient passed validation after expanding lists and numbers.
TOO_MANY_RECIPIENTS	400	The send resolves to more than 1000 recipients. data carries { count, max }.
CONTACT_NOT_FOUND	404	No contact with that id exists for your account.
LIST_NOT_FOUND	404	No contact list with that id exists for your account.
LIST_NAME_TAKEN	409	A contact list with that name already exists.
SENDER_ID_NOT_APPROVED	403	The sender ID is neither shared nor approved for your account. Nothing is charged.
OTP_INVALID	400	The code is wrong, expired, already used, or has had 5 wrong attempts. message says which; safe to show the user.
OTP_RATE_LIMITED	429	This number has been sent 5 codes in the last 24 hours.
IDEMPOTENCY_KEY_CONFLICT	409	The Idempotency-Key was reused with a different body.
PROVIDER_SEND_FAILED	502	The upstream network could not be reached.
RATE_LIMITED	429	Too many requests. Back off and retry.
NOT_FOUND	404	The requested resource does not exist.
INTERNAL_ERROR	500	An unexpected server error. Safe to retry idempotently.

Branch on code

A business 403 (API_KEY_SCOPE_DENIED) is not the same as an auth 403 (FORBIDDEN). Keying on code keeps your handling correct as the API grows.

Next: API reference