Errors & status codes
The API uses standard HTTP status codes and returns a clear JSON error on failure.
Error shape
{
"error": "Insufficient credit"
}Validation errors also include an issues array describing each problem.
Status codes
| Code | Meaning | What to do |
|---|---|---|
| 200 | Success | Read the body. |
| 202 | Accepted and scheduled | The message will send at its scheduled time. |
| 400 | Invalid request | Check the issues array and fix the payload. |
| 401 | Bad API key | Check the key and the Authorization header. |
| 402 | Insufficient credit | Top up your balance. |
| 404 | Not found | The id does not exist, or is not yours. |
| 409 | Conflict | For example, cancelling a message that already sent. |
| 429 | Rate limited | Back off and retry after a short wait. |
| 502 | Upstream error | A network or provider failed. Credit for a failed send is refunded. |
Retrying safely
On a timeout or 5xx, retrying a send is safe only if you passed an idempotencyKey. The same key returns the original message instead of sending again. See Send an SMS.