MessagePortAlways 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 is past its payment due date and has been limited, sends are rejected with 406 and nothing is sent:
{
"message": "Account Limit Reached",
"required": 102,
"balance": 11,
"is_postpaid": true
}Pay the overdue balance, or contact your account manager, to lift the limit.
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.