Always check the HTTP status code of every response. A 2xx code means the request succeeded. A 4xx code means something in the request needs fixing, and a 5xx code means something went wrong on our side.
Send Accept: application/json with every request so errors always come back as JSON.
Status codes
| Status | Meaning | What to do |
|---|---|---|
200 / 201 |
Success. | Read the response body. |
204 |
Success, no body (for example, after a delete). | Nothing. |
400 |
The request can’t be completed in the resource’s current state, such as cancelling a verification that is already verified. | Read message. |
401 |
Authentication failed: the API key is missing, invalid or disabled. | Check your credentials. |
403 |
The resource belongs to another account. | Check the ID. |
404 |
The resource doesn’t exist, or the endpoint path is wrong. | Check the URL and ID. |
405 |
The HTTP method isn’t allowed on this endpoint, for example a GET to /v2/sms. |
Check the method in the API reference. |
406 |
The send needs more than your account has available. See below. | |
422 |
Validation failed. | Read errors for the fields that failed. |
429 |
Too many requests. | Back off and retry. See Rate limits. |
5xx |
Server error. | Retry with backoff. If it persists, contact support. |
Some endpoints document their own errors in the API reference.
Validation errors
A 422 response names each field that failed and why:
{
"message": "The messages field is required.",
"errors": {
"messages": ["The messages field is required."]
}
}Insufficient balance
If your account doesn’t have enough credits for a send, the whole request is rejected with 406 and nothing is sent:
{
"message": "Insufficient credits",
"required": 102,
"balance": 11,
"is_postpaid": false
}required is the number of credits the request needs, and balance is what your account has. Top up your account, or send fewer messages. Scheduled messages are not checked against your balance when you submit them.
Per-message errors
When you send messages, a request can succeed while some of its messages are rejected. Rejected messages come back in data.errors with an error_code and an error_help. See Sending messages for the list of codes.
Troubleshooting connection problems
If you don’t receive a status code at all, there is probably a network problem between your server and ours. Check firewalls, proxies, DNS and outbound HTTPS from your server.
If you get an error status, read the response body first: it usually says exactly what is wrong. Still stuck? See Support.