Errors & retries

Status codes, idempotency, and retry guidance

Error bodies include a human-readable message. SDKs surface the HTTP status and that response body.

responseJSON

{
  "message": "Invalid phone number"
}

400

Invalid input, sender, dates, or resource relationship.

401

Missing, invalid, revoked, or expired API key.

403

Key lacks permission or belongs to another organization.

404

Organization-scoped resource does not exist.

409

State, uniqueness, or idempotency conflict.

429

Used on some flows (for example contact verification) with retryAfterSeconds in the JSON body — not a general message-send Retry-After header.

5xx

Transient failure. Retry safe requests with backoff.

Idempotency

Send Idempotency-Key (max 200 chars) on every transactional send. The same key + payload returns the original message. A different payload with the same key returns 409.