Errors
All errors have the same shape:
{ "error": { "code": "TEXT_TWO_PARTS_REQUIRED", "message": "Ce message dépasse 160 caractères : envoyez-le en 2 SMS…", "details": { "length": 212, "max": 160 } } }
Rely on code, which is stable; message is a human-readable text that may change. details is optional.
| HTTP | code |
Case |
|---|---|---|
| 400 | VALIDATION_FAILED |
Invalid request (field of the wrong type, malformed header) |
| 401 | AUTH_REQUIRED |
API key missing, invalid or revoked |
| 402 | INSUFFICIENT_CREDITS |
Not enough credits for this SMS (or these 2 SMS); nothing is queued |
| 403 | ACCOUNT_SUSPENDED |
Account suspended |
| 403 | VERIFICATION_REQUIRED |
Identity or business to be verified before sending to a third party (only the test SMS to your own verified number goes through before that) |
| 404 | NOT_FOUND |
Resource missing or outside your account |
| 409 | IDEMPOTENCY_CONFLICT |
Idempotency key already used for another recipient or another sender |
| 409 | NOT_CANCELLABLE |
Cancellation of an SMS that is not scheduled or has already gone out |
| 409 | SENDER_LIMIT_REACHED |
A sender name is already under review or approved: a single custom name per account (details.current, details.status) |
| 409 | SENDER_NAME_REFUSED |
This name has already been refused for your account (details.reason): suggest another one |
| 409 | API_KEY_LIMIT |
2 active API keys at most |
| 422 | PHONE_INVALID |
Malformed number |
| 422 | PHONE_NOT_COVERED |
Country not open (today, only Cameroon is), or landline number |
| 422 | TEXT_INVALID |
Empty text, text with control characters (except line breaks), or text emptied by the conversion to the SMS alphabet |
| 422 | TEXT_TWO_PARTS_REQUIRED |
More than 160 characters: send again with "allowTwoParts": true to send it as 2 SMS |
| 422 | TEXT_TWO_PARTS_MAX |
Longer than 2 SMS (about 310 characters): shorten the text |
| 422 | SENDER_INVALID |
Sender in the wrong format (2 to 11 letters, digits or spaces) |
| 422 | SENDER_NOT_APPROVED |
Sender not approved yet |
| 422 | SENDER_NOT_ALLOWED |
Own sender requested by an individual |
| 422 | SCHEDULE_INVALID |
Scheduling date without a time zone, in the past, or more than 30 days ahead |
| 429 | RATE_LIMITED |
More than 10 requests per second for the same key (burst of 20): wait for the number of seconds in the Retry-After header, then retry with the same Idempotency-Key |
A 4xx rejection never debits any credit.
Reasons for a message failure (errorCode)
An accepted message can end in FAILED or CANCELLED. errorCode gives the reason, for example:
errorCode |
Meaning | Credits |
|---|---|---|
OPERATOR_INACTIVE |
Recipient's network not served or unavailable | Given back |
PART1_NOT_DELIVERED |
2-SMS message: delivery of part 1 not confirmed within 15 minutes, part 2 cancelled | Part 2 given back |
PART1_FAILED |
2-SMS message: part 1 failed, part 2 never sent | Part 2 given back |
SEND_INTERRUPTED |
Sending interrupted on our side | Given back |
CANCELLED |
Scheduled SMS cancelled by you | Given back |