Errors and the response envelope

The response envelope

{ "success": true, "data": { }, "request_id": "req_8ecdcb4ce2ae4290" }

{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Wallet balance is not enough for this send.",
    "resolution": "Fund the wallet and retry."
  },
  "request_id": "req_8ecdcb4ce2ae4290"
}

HTTP/1.1 429 Too Many Requests
Retry-After: 23

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many API send requests for this workspace.",
    "resolution": "Try again in about 23 seconds.",
    "retry_after_seconds": 23
  },
  "request_id": "req_2f1e0d9c8b7a6958"
}

• code is stable. Branch on it, never on message or resolution, which may be reworded.
• resolution is written for your developers, not for your end users.
• retry_after_seconds and the Retry-After header come with rate-limit refusals.
• request_id is also sent as the x-request-id header. Log it with every call. To use your own, send X-Request-ID matching [A-Za-z0-9_-]{8,64}; anything else is replaced.

Error codes

Codes about a message's delivery, such as INVALID_RECIPIENT or delivery_expired, are not request errors. They appear on the message itself; see why a message failed.

What to retry

Retry

Network errors, timeouts, 429 (after Retry-After), and 500, 502, 503 and 504, with the same Idempotency-Key and exponential backoff.

Fix, then send

Every other 4xx. Resending unchanged returns the same error.

Wait for the first

409 idempotency_conflict with the message "still being processed": the original request is running. Retry in a few seconds.

export function classify(status, error) {
  if (status === 429 || status >= 500) return "retry";
  if (error.code === "insufficient_balance") return "fund-wallet";
  if (error.code.startsWith("sender_id_")) return "fix-sender-id";
  return "fix-request";
}

Asking for help

Include the request_id, the endpoint, the time and the error code. For a delivery question, include the message_id or batch_id. The request_id is how a request is found in Sendozi's logs.