Errors and limits

Error envelope

Service errors use a compact JSON envelope:

{
  "error": {
    "message": "Human-readable summary",
    "code": "MACHINE_READABLE_CODE",
    "details": {}
  }
}

Do not parse the message. Branch on the HTTP status and stable code when present.

Common statuses

• 400 — request validation failed. Correct the payload before retrying.
• 402 — payment is required or payment verification failed. Follow the x402 challenge.
• 403 — the target URL is blocked by policy. Do not retry the same URL.
• 413 — the upstream response exceeds the configured limit.
• 429 — the route's rate limit was exceeded. Respect retry headers and back off.
• 502 — a direct upstream fetch failed.
• 503 — a required upstream integration is unavailable or not configured.

Retry policy

Retry transient 429, 502, and 503 responses with exponential backoff and jitter. Cap attempts, preserve payment identifiers, and avoid retrying validation or policy failures.

Rate-limit identity

Paid traffic is limited by payment or wallet identity rather than relying only on source IP. Individual routes can publish different limits. Limits protect upstream capacity and do not replace your own concurrency controls.

Observability

Responses include request correlation metadata where available. Preserve it in logs when reporting a failure, but never log wallet private keys or full payment payloads.