Responses

The SMS API returns JSON responses for both successful and failed requests.

Response format

Successful response

A successful request returns HTTP 200.

{
  "success": true,
  "message": "SMS queued successfully.",
  "error": null,
  "data": {
    "batch_id": "20bc680b-974d-4f33-affa-273414ebb77f",
    "sms_count": 1,
    "total_recipients": 2,
    "cost_cents": 200,
    "status": "queued"
  }
}

Success fields

Field	Description
`success`	Indicates whether the request was successful.
`message`	Description of the result.
`error`	`null` for successful requests.
`data.batch_id`	Unique ID for the SMS request.
`data.sms_count`	Number of SMS parts in the message.
`data.total_recipients`	Number of recipients.
`data.cost_cents`	Total cost of the request in cents.
`data.status`	Current request status.

The batch_id identifies the original request and is also used to associate delivery reports with the request.

Error response

Failed requests use the following structure:

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

Error fields

Field	Description
`success`	Always `false` for an error response.
`message`	Human-readable description of the error.
`error`	Machine-readable error code.
`data`	`null` for error responses.

HTTP status codes

The API uses standard HTTP status codes to indicate the result of a request.

Status	Meaning
`200`	Request accepted and SMS queued.
`402`	Insufficient account balance.
`403`	Sender name is not allowed for the account.
`404`	Account or required resource was not found.
`422`	Request validation failed.
`429`	Rate limit exceeded.
`500`	Internal server error.

Error codes

Common error codes include:

Error code	HTTP status	Description
`INVALID_REQUEST`	422	The request is invalid.
`INVALID_RECIPIENT_COUNT`	422	No recipients were provided.
`MAX_RECIPIENTS_EXCEEDED`	422	More than 100 recipients were provided.
`INVALID_MOBILE`	422	One or more mobile numbers are invalid.
`INVALID_MESSAGE`	422	The message is invalid.
`SMS_PARTS_EXCEEDED`	422	The message exceeds 6 SMS parts.
`IP_NOT_ALLOWED`	403	The request came from an address this application is not allowed to use.
`SENDER_NOT_FOUND`	422	The sender name does not exist on the account.
`SENDER_NOT_ALLOWED`	403	The sender name is not allowed for the account.
`ACCOUNT_NOT_FOUND`	404	The account could not be found.
`WALLET_NOT_FOUND`	500	The account wallet could not be found.
`INSUFFICIENT_BALANCE`	402	The account does not have enough balance.
`RATE_LIMIT_EXCEEDED`	429	The request rate limit has been exceeded.
`INTERNAL_SERVER_ERROR`	500	An unexpected server error occurred.

See Errors for more information about handling individual errors.