eSMS AfricaeSMS Africa
API ReferenceSMS API

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", "...": "..." }
}
FieldDescription
error.codeStable code to branch on (see the table below).
error.messageOne short sentence, safe to show to your users. It never contains links, email addresses, phone numbers or instructions.
error.request_idCorrelation ID, also returned in the X-Request-Id header.
error.detailsOptional 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: 3f9a1c2b4d5e6f708192a3b4c5d6e7f8

All error codes

(value) marks a value filled in at run time, such as a country name. Some codes have more than one message.

HTTPcodeExact error.message
400bad_requestA 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
400destination_unavailableSMS to (value) is not available yet.
400destinations_unavailableNone of the recipients are in an available country.
Some recipient numbers are invalid.
Some recipients are in countries that are not available yet.
400empty_messageThe message is empty.
400feature_not_enabled(value) is not enabled on this platform yet.
400international_price_unsetInternational pricing is not configured for (value).
400invalid_audienceUnknown audience source type (value)
400invalid_binaryBinary 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)
400invalid_callback_urlcallback_url must be a public https URL
400invalid_destinationThe destination country could not be determined.
400invalid_message_typemessage_type must be transactional or promotional
400invalid_optionFlash 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)
400invalid_phoneThe 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.
400invalid_phone_lengthThe phone number has the wrong length for (value).
400invalid_quiet_hours(varies)
400invalid_scheduleSchedule 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
400invalid_statusstatus must be one of (value)
400invalid_timezoneUnknown timezone (value) (use an IANA name like Africa/Lagos)
400invalid_workspaceX-Workspace must be a workspace id.
400legacy_campaignRetry is available for campaigns sent with the new engine.
400missing_country_codeThe phone number has no country code.
400missing_merge_fieldSome recipients have no value for (value).
400missing_selectorProvide verification_id or to
400no_routeSMS to this country is not available yet.
400nothing_to_retryNo failed recipients to retry.
400phone_not_verifiedAdd and verify your phone number in your profile to receive tests.
400recipients_requiredPass recipients (with a template) or messages.
400recurrence_endedThe repeat rule has no future runs.
400sandbox_no_retrySandbox (test) messages cannot be retried.
400sandbox_no_scheduleTest keys cannot schedule sends.
400scheduled_international_unsupportedInternational-rate bulk sends cannot be scheduled.
400scheduled_needs_listScheduled bulk sends need a contact list.
400template_missing_codeTemplate must contain the {code} placeholder.
400template_requiredPass template (or template_id) or a text per recipient.
400template_too_longTemplate must be 480 characters or fewer.
400text_requiredEvery entry in messages needs text.
400to_requiredPass to with up to 3 of your own numbers.
400too_many_recipientsAt most (value) inline recipients per request; use POST /v1/imports for bigger lists.
400unsupported_channelOnly the 'sms' channel is available.
400unsupported_wallet_currencyWallet currency (value) is not supported for sending.
401unauthorizedInvalid API key
Invalid or expired token
Invalid token type
Not authenticated
Session has been revoked
402insufficient_balanceInsufficient 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.
402payment_requiredInsufficient balance.
403account_suspendedThis account is paused for a payment review.
This account is suspended.
403app_disabledThis Verify app is disabled.
403country_blockedSending to (value) is disabled for this account.
403country_not_allowedThis Verify app does not allow (value). Allowed: (value).
403country_not_enabledSending to (value) is not enabled for this account.
403forbiddenAdmin access required
403insufficient_scopeThis API key is not authorised for '(value)'.
403no_accountSend refused: no account context.
403not_a_memberYou are not a member of this workspace.
403recipient_opted_outRecipient has opted out.
The recipient has opted out.
403role_forbiddenOnly an approver, an admin or the owner can approve campaigns.
Only an approver, an admin or the owner can reject campaigns.
403route_country_mismatchThis number cannot be sent on the selected route.
route (value) can only carry (value) numbers.
403self_approvalYou submitted this campaign - another approver must approve it (maker-checker).
403sender_id_requiredA registered sender ID is required for (value).
403sender_not_approvedNo sender ID available for (value).
Sender ID '(value)' is not approved for (value).
403support_onlySupport access required.
404app_not_foundVerify app '(value)' not found
404group_not_foundContact group (value) not found
404import_not_foundImport (value) not found
404not_foundBatch not found
Campaign not found
Contact list (value) not found
Message not found
Segment not found
Verification not found
404segment_not_foundSegment (value) not found
404template_not_foundTemplate not found
404workspace_not_foundWorkspace not found.
409busyPause or cancel the campaign before deleting it.
Wait for the campaign to finish before retrying failed recipients.
409conflictDuplicate request (idempotency conflict)
409delivery_being_confirmedThis message is still being confirmed with the network.
409duplicate_messageAn identical message was sent to this number in the last 5 minutes.
409finishedThe campaign is already (value).
409has_historyA campaign that sent messages cannot be deleted.
409idempotency_in_progressA request with this Idempotency-Key is still being processed.
409import_not_readyImport (value) is (value) - process it first
409not_cancellableOnly 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)').
409not_editableA (value) campaign can't be edited. Duplicate it instead.
A (value) campaign is already prepared.
409not_launchableA (value) campaign can't be launched.
409not_pausedOnly a paused campaign can be resumed.
409not_pendingThis campaign is not waiting for approval.
Verification is '(value)', cannot resend.
409not_runningA (value) campaign can't be paused.
413message_too_longA message renders to (value) segments; the maximum is (value).
Message is (value) segments; the maximum is (value) ((value) chars = 1 segment for (value)).
422launch_blockedThis campaign cannot be launched yet.
422route_type_mismatchThis message does not fit the route type of this account.
422validation_errorRequest validation failed
422value_too_longOne of the values is too long.
429rate_limitedRate limit exceeded: (value)
429resend_limitResend limit reached ((value) sends).
429too_many_requestsToo many verification requests for this number.
500internal_errorInternal server error
502otp_send_failedResend failed ((value)). You were not charged.
The verification code could not be sent ((value)). You were not charged.

Sender ID request errors

StatusCodeMessage
400invalid_sender_nameThis 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.)
400sender_reservedThe name is an eSMS Africa default sender ID and cannot be requested for that country.
409brand_proof_requiredThe 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 on error.message (messages may change).
  • Treat 429 and 5xx as retryable, ideally with backoff; treat 4xx (except 429) as caller errors to fix.
  • Log error.request_id / the X-Request-Id header on failures so support can trace them.

On this page