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" }
  • code is stable. Branch on it.
  • error is 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) and retry_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

HTTPCodeWhat it meansWhat to do
401UNAUTHENTICATEDNo Authorization header, or the value is not a kp_live_ or kp_test_ key.Send your key as a bearer token.
401INVALID_API_KEYThe key is unknown or revoked, or its account is disabled.Create a new key.
403INSUFFICIENT_SCOPEThe key has scopes and is missing the one this endpoint needs.Use a key with that scope, or one with no scopes.
429RATE_LIMITEDMore requests than this key's per-minute limit.Wait Retry-After seconds. See rate limits.
400INVALID_REQUESTThe body is not valid JSON, or a field is missing or invalid. param names the field.Fix the request.
400IDEMPOTENCY_KEY_REQUIREDPOST /v1/sms was sent without an Idempotency-Key.Add the header.
409IDEMPOTENCY_IN_PROGRESSA request with the same key is still being processed.Retry shortly with the same key.
422IDEMPOTENCY_KEY_REUSEDThe same key was used with a different body.Use a new key for a new request.
402INSUFFICIENT_BALANCEYour balance does not cover the cost.Top up your balance.
404NOT_FOUNDThe id does not exist, or it belongs to another account.Check the id.
400SENDER_REQUIREDThe from field is empty.Pass one of your sender IDs.
403SENDER_NOT_OWNEDThe sender ID is not registered to your account. This includes reserved platform names and look-alikes such as KP0D0D0.Request your own sender ID.
403SENDER_NOT_APPROVEDThe sender ID is yours, but pending, submitted, rejected, revoked or cancelled.Wait for approval, or request again.
403SENDER_NOT_READYApproved, but still being activated on the network (minutes).Retry in a few minutes.
503SMS_DISABLEDSMS is switched off across the platform for maintenance.Retry later.
400INVALID_RECIPIENTSOne or more to entries are not phone numbers. invalid_recipients lists them. Nothing is sent or charged.Fix the numbers. See phone number formats.
400TOO_MANY_RECIPIENTSMore than 1000 recipients in one request.Split the batch.
400MESSAGE_TOO_LONGThe text needs more than 255 parts.Shorten the text. See message parts.
400INVALID_SCHEDULEschedule_at is not RFC 3339, is in the past, or is more than 90 days ahead.Fix the time.
422ALL_RECIPIENTS_SUPPRESSEDEvery recipient is on your Do-Not-Call list. Nothing is sent or charged.Nothing to do.
502UPSTREAM_ERRORAn internal service failed.Retry with the same Idempotency-Key.
500INTERNAL_ERRORSomething 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 (after Retry-After), IDEMPOTENCY_IN_PROGRESS, SENDER_NOT_READY (in a few minutes), SMS_DISABLED (later), UPSTREAM_ERROR and INTERNAL_ERROR. Always reuse the same Idempotency-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.