Errors

The error envelope and every error code with its HTTP status and meaning.

Every error uses the same envelope. Handle by error.code (stable) rather than the message (human-readable, may change).

Error envelope

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your account balance (3) is too low to send this message (2 credits)."
  }
}

Code	HTTP	When
VALIDATION	400	Malformed JSON or missing/invalid fields.
INVALID_RECIPIENT	400	`to` is not a single valid Israeli mobile number.
MESSAGE_TOO_LONG	400	`body` exceeds 603 characters.
INVALID_PHONE	400	A contact `phone` is not a valid Israeli mobile number.
SEGMENT_NOT_FOUND	400	A referenced segment id is invalid or archived.
INVALID_API_KEY	401	Missing, malformed, or unknown bearer token.
INSUFFICIENT_CREDITS	402	Balance too low to cover the message.
SENDER_NOT_APPROVED	403	`from` is not an approved sender for the workspace. The error message lists the approved senders.
RECIPIENT_UNSUBSCRIBED	403	Opt-out enforcement is on and `to` is a contact that has unsubscribed. Not charged.
RECIPIENT_BLOCKED	403	`to` is on the workspace blocklist (marketing mode only, like RECIPIENT_UNSUBSCRIBED). Not charged.
WORKSPACE_SUSPENDED	403	The workspace is suspended.
ACCOUNT_UNDER_REVIEW	403	New accounts are briefly reviewed; until then API sends are limited to your own verified sender number (for testing). Not charged.
NOT_FOUND	404	No such message or contact in this workspace.
CONTENT_FLAGGED	422	The message body matched the platform's restricted-content policy. Not charged.
RATE_LIMITED	429	Over 60 requests/minute for this token.
INTERNAL	500	Unexpected server error - the request was not processed; safe to retry.