Errors
The error envelope, the X-Request-Id header, and every SMS API error code with its HTTP status and exact message.
Error envelope
Every error response carries a structured envelope. The detail field is kept
for backward compatibility, and error gives a stable machine-readable shape:
{
"error": {
"code": "insufficient_balance",
"message": "Insufficient balance.",
"request_id": "3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
"details": {
"hint": "Top up your balance, then send again.",
"required": 0.0192,
"available": 0.01,
"segments": 2,
"recipients": 2
}
},
"detail": { "code": "insufficient_balance", "...": "..." }
}| Field | Description |
|---|---|
error.code | Stable code to branch on (see the table below). |
error.message | One short sentence, safe to show to your users. It never contains links, email addresses, phone numbers or instructions. |
error.request_id | Correlation ID, also returned in the X-Request-Id header. |
error.details | Optional extra context for you, the developer: hint says what to do next, and fields such as to, country, required, available, enable_url and register_url depend on the error. Do not show these to your users. |
A refused send is never charged. Branch on error.code, which is stable: the wording of error.message can change.
X-Request-Id
Every response - success or error - includes an X-Request-Id header. If you
send your own X-Request-Id, it is echoed back; otherwise one is generated.
Include this value when contacting support so a failed call can be matched to a
log line.
X-Request-Id: 3f9a1c2b4d5e6f708192a3b4c5d6e7f8All error codes
(value) marks a value filled in at run time, such as a country name. Some codes have more than one message.
| HTTP | code | Exact error.message |
|---|---|---|
400 | bad_request | A message with status '(value)' cannot be retried. All recipients are opted out or duplicates At least one phone number is required At least one recipient is required Cannot detect country from phone numbers Cannot detect the country of this phone number. Invalid route code: (value) Invalid route code: (value). Invalid (value) - use ISO 8601 Message text is required No active route for country (value) No contacts found Provide at least one message id in ?ids= Provide contact_list_ids or recipients Rate check is limited to 1000 recipients per call Route no longer exists Validation is limited to 1000 numbers per call drip_rate (messages per minute, 1-5000) is required when schedule_mode is 'drip' schedule_mode must be 'now' or 'scheduled' schedule_mode must be 'now', 'scheduled' or 'drip' scheduled_at is required when schedule_mode is 'scheduled' scheduled_at must be an ISO 8601 date and time with a timezone. scheduled_at must be at least 5 minutes in the future scheduled_at must be within 7 days from now text is required |
400 | destination_unavailable | SMS to (value) is not available yet. |
400 | destinations_unavailable | None of the recipients are in an available country. Some recipient numbers are invalid. Some recipients are in countries that are not available yet. |
400 | empty_message | The message is empty. |
400 | feature_not_enabled | (value) is not enabled on this platform yet. |
400 | international_price_unset | International pricing is not configured for (value). |
400 | invalid_audience | Unknown audience source type (value) |
400 | invalid_binary | Binary payload is (value) octets; one SMS carries at most (value). UCS-2 binary data must be an even number of octets Unknown binary field(s): (value) binary must be an object: {data, udh?, data_coding?} binary.data is required (hex) binary.data_coding must be 4 (8-bit data) or 8 (UCS-2) binary.udh has a truncated information element binary.udh information element overruns the header binary.udh is too short (UDHL + at least one IE header) binary.udh length byte (UDHL) is (value) but (value) header octets follow binary.(value) must be a hex string binary.(value) must contain only hex digits 0-9 a-f binary.(value) must have an even number of hex digits (whole octets) |
400 | invalid_callback_url | callback_url must be a public https URL |
400 | invalid_destination | The destination country could not be determined. |
400 | invalid_message_type | message_type must be transactional or promotional |
400 | invalid_option | Flash and binary SMS are not supported for destinations in (value) yet. Send either text or binary, not both binary payloads are only supported on single sends flash can't be combined with binary flash must be true or false priority must be 0 (normal), 1, 2 or 3 (highest) text is required validity_period must be a whole number of minutes between 1 and (value) |
400 | invalid_phone | The phone number has an unknown country code. The phone number is empty. This is not a valid phone number. This is not a valid (value) mobile number. |
400 | invalid_phone_length | The phone number has the wrong length for (value). |
400 | invalid_quiet_hours | (varies) |
400 | invalid_schedule | Schedule within the next 12 months schedule.at is required for a scheduled campaign schedule.mode must be now, scheduled or recurring schedule.recurrence is required for a recurring campaign |
400 | invalid_status | status must be one of (value) |
400 | invalid_timezone | Unknown timezone (value) (use an IANA name like Africa/Lagos) |
400 | invalid_workspace | X-Workspace must be a workspace id. |
400 | legacy_campaign | Retry is available for campaigns sent with the new engine. |
400 | missing_country_code | The phone number has no country code. |
400 | missing_merge_field | Some recipients have no value for (value). |
400 | missing_selector | Provide verification_id or to |
400 | no_route | SMS to this country is not available yet. |
400 | nothing_to_retry | No failed recipients to retry. |
400 | phone_not_verified | Add and verify your phone number in your profile to receive tests. |
400 | recipients_required | Pass recipients (with a template) or messages. |
400 | recurrence_ended | The repeat rule has no future runs. |
400 | sandbox_no_retry | Sandbox (test) messages cannot be retried. |
400 | sandbox_no_schedule | Test keys cannot schedule sends. |
400 | scheduled_international_unsupported | International-rate bulk sends cannot be scheduled. |
400 | scheduled_needs_list | Scheduled bulk sends need a contact list. |
400 | template_missing_code | Template must contain the {code} placeholder. |
400 | template_required | Pass template (or template_id) or a text per recipient. |
400 | template_too_long | Template must be 480 characters or fewer. |
400 | text_required | Every entry in messages needs text. |
400 | to_required | Pass to with up to 3 of your own numbers. |
400 | too_many_recipients | At most (value) inline recipients per request; use POST /v1/imports for bigger lists. |
400 | unsupported_channel | Only the 'sms' channel is available. |
400 | unsupported_wallet_currency | Wallet currency (value) is not supported for sending. |
401 | unauthorized | Invalid API key Invalid or expired token Invalid token type Not authenticated Session has been revoked |
402 | insufficient_balance | Insufficient balance for the test message ((value) (value)). Insufficient balance to retry this message. Insufficient balance. Sandbox: simulated insufficient balance (magic number). Your balance is negative. |
402 | payment_required | Insufficient balance. |
403 | account_suspended | This account is paused for a payment review. This account is suspended. |
403 | app_disabled | This Verify app is disabled. |
403 | country_blocked | Sending to (value) is disabled for this account. |
403 | country_not_allowed | This Verify app does not allow (value). Allowed: (value). |
403 | country_not_enabled | Sending to (value) is not enabled for this account. |
403 | forbidden | Admin access required |
403 | insufficient_scope | This API key is not authorised for '(value)'. |
403 | no_account | Send refused: no account context. |
403 | not_a_member | You are not a member of this workspace. |
403 | recipient_opted_out | Recipient has opted out. The recipient has opted out. |
403 | role_forbidden | Only an approver, an admin or the owner can approve campaigns. Only an approver, an admin or the owner can reject campaigns. |
403 | route_country_mismatch | This number cannot be sent on the selected route. route (value) can only carry (value) numbers. |
403 | self_approval | You submitted this campaign - another approver must approve it (maker-checker). |
403 | sender_id_required | A registered sender ID is required for (value). |
403 | sender_not_approved | No sender ID available for (value). Sender ID '(value)' is not approved for (value). |
403 | support_only | Support access required. |
404 | app_not_found | Verify app '(value)' not found |
404 | group_not_found | Contact group (value) not found |
404 | import_not_found | Import (value) not found |
404 | not_found | Batch not found Campaign not found Contact list (value) not found Message not found Segment not found Verification not found |
404 | segment_not_found | Segment (value) not found |
404 | template_not_found | Template not found |
404 | workspace_not_found | Workspace not found. |
409 | busy | Pause or cancel the campaign before deleting it. Wait for the campaign to finish before retrying failed recipients. |
409 | conflict | Duplicate request (idempotency conflict) |
409 | delivery_being_confirmed | This message is still being confirmed with the network. |
409 | duplicate_message | An identical message was sent to this number in the last 5 minutes. |
409 | finished | The campaign is already (value). |
409 | has_history | A campaign that sent messages cannot be deleted. |
409 | idempotency_in_progress | A request with this Idempotency-Key is still being processed. |
409 | import_not_ready | Import (value) is (value) - process it first |
409 | not_cancellable | Only a scheduled batch that has not started can be cancelled (this one is '(value)'). Only a scheduled message can be cancelled (this one is '(value)'). |
409 | not_editable | A (value) campaign can't be edited. Duplicate it instead. A (value) campaign is already prepared. |
409 | not_launchable | A (value) campaign can't be launched. |
409 | not_paused | Only a paused campaign can be resumed. |
409 | not_pending | This campaign is not waiting for approval. Verification is '(value)', cannot resend. |
409 | not_running | A (value) campaign can't be paused. |
413 | message_too_long | A message renders to (value) segments; the maximum is (value). Message is (value) segments; the maximum is (value) ((value) chars = 1 segment for (value)). |
422 | launch_blocked | This campaign cannot be launched yet. |
422 | route_type_mismatch | This message does not fit the route type of this account. |
422 | validation_error | Request validation failed |
422 | value_too_long | One of the values is too long. |
429 | rate_limited | Rate limit exceeded: (value) |
429 | resend_limit | Resend limit reached ((value) sends). |
429 | too_many_requests | Too many verification requests for this number. |
500 | internal_error | Internal server error |
502 | otp_send_failed | Resend failed ((value)). You were not charged. The verification code could not be sent ((value)). You were not charged. |
Sender ID request errors
| Status | Code | Message |
|---|---|---|
400 | invalid_sender_name | This sender ID name is not allowed. (error.details.hint: use letters, numbers and a hyphen only, for example eSMS, eSMSAfrica or eSMS-UG. No spaces or underscores. Up to 11 characters.) |
400 | sender_reserved | The name is an eSMS Africa default sender ID and cannot be requested for that country. |
409 | brand_proof_required | The name looks like a protected brand. Upload the brand owner's authorisation letter first; nothing is charged. |
Campaign review items
POST /v1/campaigns/{id}/launch refuses with launch_blocked when the review finds a blocking item, and returns the items in error.details.blocking and error.details.warnings. Each item has a code and a message written for the person preparing the campaign: no_message, no_audience, no_recipients, missing_field, country_not_enabled, sender_not_approved, sender_id_required, insufficient_balance, route_type_mismatch, content_blocked, no_time, time_in_past, no_recurrence, not_prepared, low_balance, opted_out, unavailable_country, duplicates, invalid_numbers, multi_segment, unicode, too_long, quiet_hours, no_test, approval_required.
Handling errors
- Branch on
error.code, not onerror.message(messages may change). - Treat
429and5xxas retryable, ideally with backoff; treat4xx(except429) as caller errors to fix. - Log
error.request_id/ theX-Request-Idheader on failures so support can trace them.