Reference

Errors and limits

Error codes, rate limits, and how to retry.

Error answers

A failed request gets an HTTP error status and a body with a message written for people and a details.code for your code to check. Show the message; branch on the code.

402 Payment Required

{
  "statusCode": 402,
  "message": "Not enough SMS balance: this needs LKR 4.00 and the balance is LKR 1.20.",
  "details": {
    "code": "INSUFFICIENT_BALANCE",
    "needed": "4.00",
    "balance": "1.20",
    "currency": "LKR"
  }
}

Codes

Code	Status	Meaning
UNAUTHORIZED	401	No key, a wrong key, or a revoked key.
MISSING_SCOPE	403	The key doesn't have the permission this endpoint needs.
RATE_LIMITED	429	Too many requests from this key or your organization. Wait for the number of seconds in Retry-After.
QUEUE_FULL	429	Your organization already has 50,000 messages waiting to be sent. Wait for some to go out, then send again. Nothing was charged.
TEST_LIMIT_REACHED	429	Test keys have reached today’s 5,000 recipients. The limit resets at midnight UTC.
NOT_FOUND	404	The message or template doesn't exist, or belongs to the other mode (test or live).
IDEMPOTENCY_IN_PROGRESS	409	A request with the same Idempotency-Key is still running. Repeat it in a few seconds to get its result.
INSUFFICIENT_BALANCE	402	The balance doesn't cover the whole request. Nothing was sent.
SMS_NOT_ENABLED	400	SMS is not turned on for your account.
SMS_SUSPENDED	400	Sending is paused for your account. Contact support.
SENDER_ID_NOT_APPROVED	400	The sender ID isn't verified, or you have several and didn't choose one.
NO_PRICE	400	Prices aren't set up for your account yet. Contact support.
MESSAGE_TOO_LONG	400	The text is over 1,600 characters.
EMPTY_MESSAGE	400	The text (or the filled-in template) is empty.
INVALID_NUMBER	per number	Not a mobile number that can be texted. Only that number is refused.
UNSUPPORTED_COUNTRY	per number	A country we don't send to yet. Only that number is refused.
NOT_A_TEST_NUMBER	per number	In test mode, the number isn't one of your verified test numbers.

“per number” codes don’t fail the request: they appear on that number’s result in the answer, with "status": "REFUSED".

Rate limits

Each key can make 100 requests every 10 seconds, and your whole organization 300 across all its keys. Over either, you get 429 with a Retry-After header giving the seconds to wait.
Up to 50,000 of your messages can wait to be sent at once. A send that would go over is refused with QUEUE_FULL and nothing is charged.
Test keys can send to 5,000 numbers a day.

To text many people, send up to 100 numbers per request instead of one request each.

Large sends go out steadily rather than all at once, and a single urgent text (from you or anyone else) doesn’t wait behind a big campaign: messages from an organization with a long queue take turns with everyone else’s. Send one-time codes and order updates from a transactional sender ID; they always go before promotional messages.

When you get 429 or a 5xx, wait and try again, with growing waits. Send an Idempotency-Key with every send so a retry never texts twice.