Errors
Every error from a /v1 endpoint has the same shape and a stable code your program can act on.
Error shape
Error
{ "error": "Human readable message, may change", "code": "STABLE_MACHINE_CODE" }codeis stable. Branch on it.erroris for people reading logs. Its wording may change, so never match on it.- Some errors add fields:
param(the field that is wrong),invalid_recipients(the numbers that are not phone numbers) andretry_after(seconds to wait).
Example: 400 INVALID_RECIPIENTS
{
"error": "One or more recipients are not valid phone numbers",
"code": "INVALID_RECIPIENTS",
"invalid_recipients": ["12345"]
}Error codes
| HTTP | Code | What it means | What to do |
|---|---|---|---|
| 401 | UNAUTHENTICATED | No Authorization header, or the value is not a kp_live_ or kp_test_ key. | Send your key as a bearer token. |
| 401 | INVALID_API_KEY | The key is unknown or revoked, or its account is disabled. | Create a new key. |
| 403 | INSUFFICIENT_SCOPE | The key has scopes and is missing the one this endpoint needs. | Use a key with that scope, or one with no scopes. |
| 429 | RATE_LIMITED | More requests than this key's per-minute limit. | Wait Retry-After seconds. See rate limits. |
| 400 | INVALID_REQUEST | The body is not valid JSON, or a field is missing or invalid. param names the field. | Fix the request. |
| 400 | IDEMPOTENCY_KEY_REQUIRED | POST /v1/sms was sent without an Idempotency-Key. | Add the header. |
| 409 | IDEMPOTENCY_IN_PROGRESS | A request with the same key is still being processed. | Retry shortly with the same key. |
| 422 | IDEMPOTENCY_KEY_REUSED | The same key was used with a different body. | Use a new key for a new request. |
| 402 | INSUFFICIENT_BALANCE | Your balance does not cover the cost. | Top up your balance. |
| 404 | NOT_FOUND | The id does not exist, or it belongs to another account. | Check the id. |
| 400 | SENDER_REQUIRED | The from field is empty. | Pass one of your sender IDs. |
| 403 | SENDER_NOT_OWNED | The sender ID is not registered to your account. This includes reserved platform names and look-alikes such as KP0D0D0. | Request your own sender ID. |
| 403 | SENDER_NOT_APPROVED | The sender ID is yours, but pending, submitted, rejected, revoked or cancelled. | Wait for approval, or request again. |
| 403 | SENDER_NOT_READY | Approved, but still being activated on the network (minutes). | Retry in a few minutes. |
| 503 | SMS_DISABLED | SMS is switched off across the platform for maintenance. | Retry later. |
| 400 | INVALID_RECIPIENTS | One or more to entries are not phone numbers. invalid_recipients lists them. Nothing is sent or charged. | Fix the numbers. See phone number formats. |
| 400 | TOO_MANY_RECIPIENTS | More than 1000 recipients in one request. | Split the batch. |
| 400 | MESSAGE_TOO_LONG | The text needs more than 255 parts. | Shorten the text. See message parts. |
| 400 | INVALID_SCHEDULE | schedule_at is not RFC 3339, is in the past, or is more than 90 days ahead. | Fix the time. |
| 422 | ALL_RECIPIENTS_SUPPRESSED | Every recipient is on your Do-Not-Call list. Nothing is sent or charged. | Nothing to do. |
| 502 | UPSTREAM_ERROR | An internal service failed. | Retry with the same Idempotency-Key. |
| 500 | INTERNAL_ERROR | Something unexpected went wrong. | Retry with the same Idempotency-Key. |
Voice and verification
The verify and calls endpoints return INVALID_REQUEST when to or the digits are missing, NOT_FOUND for an unknown call or verification, and INSUFFICIENT_BALANCE when your balance does not cover the call. Authentication and rate limit errors are the same as above.
Which errors to retry
- Retry
RATE_LIMITED(afterRetry-After),IDEMPOTENCY_IN_PROGRESS,SENDER_NOT_READY(in a few minutes),SMS_DISABLED(later),UPSTREAM_ERRORandINTERNAL_ERROR. Always reuse the sameIdempotency-Key. - Do not retry the rest unchanged. They describe a problem with the request, the key or the account that a retry will not fix.