API Response Guide

Stable response codes and retry guidance for Sending API v1.

← Back to API Guide

Every response contains an X-Request-ID header and matching request_id JSON field. Keep this value when contacting support.

Success responses

HTTPMeaningRetry?
202Validated, charged and queued for processing.No.
200An existing result was returned for the same Idempotency-Key.No; use the returned message ID.

Error responses

HTTPerror_codeMeaningRecommended action
400INVALID_JSON
INVALID_BODY		Malformed JSON or non-object body.Correct the request; do not retry unchanged.
401AUTH_MISSING
AUTH_INVALID		Missing, inactive or invalid API key.Check or rotate the key.
403ACCOUNT_NOT_FOUND
ACCOUNT_DISABLED
ACCOUNT_EXPIRED		The account cannot send.Resolve the account status.
404TEMPLATE_NOT_FOUNDTemplate is absent, inactive or owned by another account.Use an active template belonging to the API-key owner.
409INSUFFICIENT_CREDITS
DEVICE_NOT_CONNECTED
META_NUMBER_UNAVAILABLE
TEMPLATE_NOT_APPROVED		The request conflicts with current account, sender or template state.Correct the state, then retry with the same Idempotency-Key.
413PAYLOAD_TOO_LARGERequest exceeds 1 MB.Reduce the request size.
415UNSUPPORTED_MEDIA_TYPEPOST is not application/json.Set the correct Content-Type.
422INVALID_RECIPIENT
INVALID_MESSAGE
MESSAGE_TOO_LONG
INVALID_TEMPLATE_PARAMETERS
TEMPLATE_PARAMETERS_MISSING
INVALID_MEDIA
INVALID_LOCATION
INVALID_SEND_TIME		One or more request fields failed validation.Correct the identified field.
429RATE_LIMITEDToo many requests for this API key.Wait for Retry-After, then retry with the same Idempotency-Key.
500INTERNAL_ERRORUnexpected server/database failure.Retry with exponential backoff and the same Idempotency-Key.

Error example

HTTP/1.1 422 Unprocessable Content
{
  "success": false,
  "error": "A valid recipient number is required",
  "error_code": "INVALID_RECIPIENT",
  "request_id": "..."
}

Safe retry policy

  1. Create one unique Idempotency-Key for the logical message.
  2. Reuse that same key after timeouts, HTTP 429 or HTTP 500.
  3. Use exponential backoff, for example 2, 5, 15 and 30 seconds.
  4. Do not generate a new key for a retry; that may create another billable message.

Legacy response mode

Requests without X-API-Version: 1 retain the original JSON fields and HTTP-200 application-error behaviour. New fields such as error_code, request_id and message_id are additive and may safely be ignored by old clients.