Errors and rate limits: what to retry, what to surface

Most production issues don't come from the happy path — they come from how integrations handle the unhappy ones. This is the reference for what the platform returns and how to react.

Status codes you'll see

Error response shape

Every error has the same body:

Copy{
  "error": {
    "code": "validation_failed",
    "message": "to_number must be in E.164 format",
    "field": "to_number",
    "request_id": "req_abc123"
  }
}

Always log request_id. When you open a support ticket, that's the only piece of info we need to trace the request through every internal hop.

Rate limits

Limits are per-API-key, sliding window. Each response includes:

CopyX-RateLimit-Limit: 600
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1714998000

When you hit zero:

CopyHTTP/1.1 429 Too Many Requests
Retry-After: 12

Retry-After is in seconds. Wait that long, then retry. If you're seeing 429 frequently, contact support to discuss raising your limits — for high-volume customers we tune them per workspace.

Retrying POSTs safely

There is no idempotency header. An earlier version of this page documented one with a 24-hour response cache; it was never built and the section was removed on 6 October 2026.

For POSTs that create something, a blind retry can create it twice — in particular POST /v1/calls can place a second call and charge for it. Safe pattern:

1. Put your own request id in metadata ({"metadata": {"req": "…"}}).
2. On timeout or 5xx, query first — GET /v1/calls?agent_id=… and look for your id in metadata — and only then retry.
3. For wallet top-ups the Paddle checkout is the dedupe boundary; never re-POST /v1/wallet/topup on a timeout, open the returned URL again.

Retry strategy that works in production

Copyattempt 1 → fail with 502
wait 1s
attempt 2 → fail with 502
wait 2s
attempt 3 → fail with 502
wait 4s
attempt 4 → succeed

Caps to apply:

• max attempts: 5
• max total wait: 30s
• never retry 4xx (except 408, 429)
• always honor Retry-After if present

Most HTTP client libraries have this built in — use the library, don't reinvent it.

What's next

• Authentication — the 401 and 403 root causes
• Webhooks — retry semantics for events you receive
• Pricing — when 402 is right and what to do about it