Errors

The SMS API uses HTTP status codes and error codes to indicate why a request failed.

Error response

All API errors use the following JSON structure:

{
  "success": false,
  "message": "Error description",
  "error": "ERROR_CODE",
  "data": null
}

Validation errors

Invalid request

HTTP 422

Returned when the request is invalid.

{
  "success": false,
  "message": "Invalid request.",
  "error": "INVALID_REQUEST",
  "data": null
}

Invalid recipient count

HTTP 422

Returned when no recipients are provided.

INVALID_RECIPIENT_COUNT

Maximum recipients exceeded

HTTP 422

Returned when more than 100 recipients are included in a request.

MAX_RECIPIENTS_EXCEEDED

Invalid mobile number

HTTP 422

Returned when one or more recipient mobile numbers are invalid.

INVALID_MOBILE

Invalid message

HTTP 422

Returned when the SMS message is invalid.

INVALID_MESSAGE

SMS parts exceeded

HTTP 422

Returned when the message exceeds the maximum of 6 SMS parts.

SMS_PARTS_EXCEEDED

Sender errors

Sender not found

HTTP 422

Returned when the specified sender name does not exist on the account.

SENDER_NOT_FOUND

IP not allowed

Returned when the request comes from an address the application is not allowed to use. See IP Whitelisting.

IP_NOT_ALLOWED

Status: 403

Sender not allowed

HTTP 403

Returned when the sender name exists but is not allowed for the account.

SENDER_NOT_ALLOWED

Account and balance errors

Account not found

HTTP 404

Returned when the account associated with the API credentials cannot be found.

ACCOUNT_NOT_FOUND

Wallet not found

HTTP 500

Returned when the account wallet cannot be found.

WALLET_NOT_FOUND

Insufficient balance

HTTP 402

Returned when the account does not have enough balance to send the requested SMS.

INSUFFICIENT_BALANCE

Rate limit errors

Rate limit exceeded

HTTP 429

Returned when the request rate exceeds the allowed limit.

RATE_LIMIT_EXCEEDED

The response includes a Retry-After header indicating how long the client should wait before retrying.

Retry-After: 1

See Rate Limits for more information.

Server errors

Internal server error

HTTP 500

Returned when an unexpected error occurs while processing the request.

INTERNAL_SERVER_ERROR

Clients should avoid immediately retrying repeatedly after receiving a 500 response. If retrying is appropriate, use the same Idempotency-Key for the original request.

Handling errors

Applications should use the HTTP status code and error field to determine how to handle a failed request.

For example:

HTTP 422
    ↓
Read error code
    ↓
Fix request
    ↓
Send request again

For a 429 response:

HTTP 429
    ↓
Read Retry-After
    ↓
Wait
    ↓
Retry

For retries of the same SMS operation, reuse the original Idempotency-Key.