Errors

Every error is JSON with a stable envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "`to` must be a valid US/Canada number in E.164 format.",
    "param": "to",
    "request_id": "req_8Fq2ZkT0aLw4nXcV7pHs"
  }
}

Request IDs

Every response from an endpoint that takes your API key, success or error, carries an X-Request-Id header (req_…), and error bodies repeat it as request_id. Look it up in the console under Logs to see the request and response as we received and sent them (API keys, secrets, verification codes, and card data are redacted; bodies are truncated at 8 KB; logs are kept for 30 days). Include it when you contact support.

Codes

Delivery failures

A message that was accepted but not delivered has status: "failed" and a failure object, on the message and in the message.failed webhook: { code, title, explanation, action, carrier_code }. The codes are stable; switch on code, show title and explanation to your team, and follow action. carrier_code is the carrier's own code when it sent one, for support conversations.

Some sends are refused by one of our checks before any carrier sees them: the recipient opted out, it is quiet hours for a marketing message, the sending number is not registered yet, the content is blocked, the number is rate limited, or the send would pass your spending limit or your credit balance. Those answer 402, 403 or 429, the error carries the same failure object, and the attempt is stored as a message with status: "blocked" (its id is message_id in the error), so one handler covers both and your log shows every attempt:

{
  "error": {
    "code": "recipient_opted_out",
    "message": "This recipient opted out of your messages on Oct 5, 2026 at 8:42 AM UTC by replying STOP. Nothing was sent and you were not charged. They can opt back in by texting START to your number.",
    "param": "to",
    "opted_out_at": "2026-10-05T08:42:00.000Z",
    "opted_out_via": "sms_keyword",
    "opted_out_method": "keyword",
    "failure": { "code": "opted_out", "title": "Recipient opted out", "explanation": "...", "action": "Recommended: ...", "carrier_code": null }
  }
}

Every code except content_blocked, screen_unavailable, spend_limit_reached, insufficient_credits and sender_not_registered (sandbox numbers are never registered) has a sandbox number that produces it, so you can test the handling before going live.

Success codes

200 and 201 mean done. 202 (on POST /v1/messages) means accepted and queued: a temporary carrier problem is being retried for you. A replayed idempotent request returns the original status code with an Idempotent-Replayed: true header.

Rate limits

Default 60 requests/minute per key. 429s include a Retry-After header. Successful quota-limited calls include X-Quota-Remaining.