Errors & limits

Error format

All errors return JSON with a stable, machine-readable code:

{
  "error": "Customer not found",
  "code": "NOT_FOUND"
}

Validation failures (422) add a details object describing the offending fields. Plan-limit errors may add an upgradeUrl.

Error codes

The ERASURE_* conflicts leave the customer's data in place for operator review — they are not transient, so don't retry them automatically. See Customers.

Rate limits

Limits are per-minute. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining. Exceeding a limit returns 429 RATE_LIMITED with a Retry-After header.

Capture scales with your plan, and each agent gets its own budget — a busy support agent can't eat into what your sales agent has left. Both run at the full rate for your plan:

Recall endpoints are deliberately generous (600/min) because agents call them on every turn.

Idempotency

POST /capture accepts an optional idempotencyKey (≤128 chars). Replaying the same key with the same payload within 24 hours returns the original cached result instead of re-processing. Reusing a key with a different payload returns 409 IDEMPOTENCY_KEY_REUSED.

If a request with that key is still in flight, you get 409 IDEMPOTENCY_IN_PROGRESS — wait briefly and retry.

await client.capture(
  [{ role: 'user', content: userMessage }],
  { customerId },
  { idempotencyKey: `turn-${conversationId}-${turnIndex}` },
)

Use idempotency keys anywhere captures may be retried — webhook-driven flows, unreliable networks, or any fire-and-forget pattern that may replay.

Retry guidance

The TypeScript and Python SDKs retry 429, 5xx, and timed-out requests automatically with a jittered, increasing delay (maxRetries / max_retries, default 3). They do not read Retry-After. The Rust SDK does not retry automatically. For your own HTTP clients:

• 429 — respect the Retry-After header if present, otherwise back off exponentially
• 503 — transient service issue; retry with backoff
• 409 IDEMPOTENCY_IN_PROGRESS — wait 1–2 seconds and retry with the same key
• 4xx (other) — don't retry; fix the request

Phone number normalization

Phone numbers sent to any endpoint are normalized best-effort to E.164:

• 10 digits → +1… (US/CA assumed)
• 11 digits starting with 1 → +…
• Otherwise + is prepended

Send E.164 directly (+14155550101) to avoid ambiguity.

What's next

• Authentication — API key scopes and security model
• Capture — idempotency in the capture flow
• AI agents — retry patterns in agentic tool calls