Reference
API errors and error codes
Errors use HTTP status codes and always have the same JSON body. param names the field when one field is the cause. Every answer has an X-Request-Id header: quote it in a support ticket.
{
"error": {
"code": "text_too_long",
"message": "The text is longer than 10 segments (1,530 GSM-7 or 670 UCS-2 characters).",
"param": "text",
"doc_url": "https://bulksmsapi.cc/en/docs/errors#text_too_long"
}
}Codes
| code | HTTP | Cause | Money |
|---|---|---|---|
| invalid_json | 400 | The body is not a JSON object, or Content-Type is not application/json. | Fix the body. Nothing was charged. |
| invalid_request | 400 | A field is missing or has the wrong type; param names it. | Fix the field. Nothing was charged. |
| invalid_number | 400 | No number in the request could be read as E.164 (+ and 7 to 15 digits). | Check the numbers. Nothing was charged. |
| unsupported_country | 400 / 404 | No priced country matches the numbers, or GET /v1/pricing/{country} has an unknown code. | Check the country list. Nothing was charged. |
| text_too_long | 400 | The text needs more than 10 segments. | Shorten the text. Nothing was charged. |
| too_many_recipients | 400 | More than 10,000 recipients in one request. | Split the list. Nothing was charged. |
| schedule_out_of_range | 400 | send_at is not a valid time between 2 minutes and 45 days from now. | Pick another time. Nothing was charged. |
| suppressed | 400 | Every number in the request is on your do-not-send list (Settings in the console). | Nothing was sent or charged. |
| unauthorized | 401 | The Authorization header is missing, malformed, or the key was revoked. | Send a live key. Nothing was charged. |
| top_up_required | 402 | The balance is lower than the cost of the request; the message says both amounts. | Top up and send again. Nothing was charged. |
| not_found | 404 | The id does not exist in this account, or the endpoint does not exist. | Check the id and the path. |
| idempotency_conflict | 409 | The Idempotency-Key was used with a different request body in the last 24 hours. | Use a new key for a new request. |
| not_cancelable | 409 | Only a scheduled batch can be canceled; this one has started or finished. | Nothing changed. |
| rate_limited | 429 | The key made more than 600 requests in the last 60 seconds. | Wait Retry-After seconds. Nothing was charged. |
| server_error | 500 | Something failed on our side. | Retry with the same Idempotency-Key. |
Retrying
- 4xx errors other than 429 need a change to the request; sending the same request again gives the same error.
- On 429, wait the number of seconds in Retry-After.
- On 5xx or a network timeout, retry with the same Idempotency-Key: if the first request was accepted, you get its answer back instead of a second send.