Errors and the response envelope

The response envelope

Every response, success or failure, has the same shape: a success boolean, either data or error, and a request_id. Write your client against the envelope once and every endpoint behaves consistently.

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

{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "The wallet balance does not cover this send.",
    "resolution": "Top up the wallet and retry."
  },
  "request_id": "req_8ecdcb4ce2ae4290"
}

• code is the stable, machine-readable identifier. Branch on this, never on the message text.
• message describes what happened.
• resolution says what to do about it. It is written for a developer, not for display to an end user.
• request_id is also returned as the x-request-id header. Log it on every request.

Error codes

The order checks run in

A production send is checked in a fixed order and returns the first failure without charging. Knowing the order saves time: an insufficient_balance error means everything before it already passed.

1. Platform maintenance mode
2. Recipients valid for the channel
3. Content passes policy checks
4. No recipient suppressed
5. API key active
6. Workspace active
7. KYC approved and production access granted
8. Channel active for the workspace
9. SMS: sender ID approved
10. Wallet exists and is not frozen
11. Balance covers the estimated cost
12. Provider available

Sandbox sends run checks one to four only.

Handling errors in code

const PERMANENT = new Set([
  "invalid_request",
  "invalid_recipient",
  "message_policy_violation",
  "unauthorized",
  "forbidden",
  "kyc_required",
  "sender_id_not_approved",
  "sender_id_route_mismatch",
  "sender_id_unclassified",
  "channel_not_active",
  "recipient_suppressed",
  "api_key_blocked",
  "wallet_frozen",
  "idempotency_conflict",
]);

export function classify(error: { code: string }) {
  if (PERMANENT.has(error.code)) return "fix";
  if (error.code === "insufficient_balance") return "fund";
  if (error.code === "rate_limit_exceeded") return "backoff";
  return "retry";
}

Escalating

When something needs support, the request_id is the single most useful thing you can supply - it is how a failure is traced through the platform logs. Include it, the endpoint, the approximate time and the error code. For a delivery question, include the message id as well.