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)."
}
}Some errors add details, an array with one entry per problem ({ path, message } on VALIDATION; { code: "RESUBSCRIBE_NOT_ALLOWED" } on the opt-out rule).
| 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. |
| IDEMPOTENCY_CONFLICT | 409 | The Idempotency-Key was already used for a different request: another recipient or body on POST /messages, another phone or sender on POST /verify. Use a new key. |
| 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. |
| UNSUPPORTED_PREFIX | 400 | Verify: a 056/059 number asked for a code. These prefixes never return a delivery receipt. Not charged. |
| VERIFY_COOLDOWN | 429 | Verify: a resend inside 60 seconds of the last send. Retry-After says how long. Not charged. |
| VERIFY_PHONE_RATE_LIMITED | 429 | Verify: this phone already received 5 codes in the last hour (across all of Sendy). Not charged. |
| VERIFY_DAILY_CAP | 429 | Verify: the workspace hit its daily code limit (1,000 by default; support can raise it). Not charged. |
| VERIFY_MAX_SENDS | 409 | Verify: 3 codes were already sent for this verification. Start a new one. |
| VERIFY_CLOSED | 409 | Verify: resend on a verification that is approved, failed or expired. |
| VERIFY_SEND_FAILED | 502 | Verify: the carrier rejected the message for this number. Nothing persisted, not charged. |
| VERIFY_UNAVAILABLE | 503 | Verify: the gateway refused for now (retry) or did not confirm in time. In the second case `error.details` carries `verification_id`: the code may still arrive and works, and calling start again for the number returns that verification without a second code. Not charged. |
| VERIFY_IN_PROGRESS | 409 | Verify: another request is sending this number's code right now. Retry after `Retry-After` to get the verification. Not charged. |
| INTERNAL | 500 | Unexpected server error - the request was not processed; safe to retry. |