Errors

Every error has the same shape:

{
  "error": {
    "code": "invalid_request",
    "message": "sellAmount: Expected a value greater than 0",
    "request_id": "req_…",
    "details": { "issues": [ … ] }
  }
}

code is stable and machine-readable — branch on it, not on message. request_id is also returned as the X-Request-Id header; quote it when you report a problem. details is present for validation errors and lists the offending fields.

Codes

HTTP	code	Meaning	What to do
400	invalid_request	Bad or missing parameter, or a chain your key can't use	Fix the request; check details
401	unauthorized	Missing, malformed, revoked, or unknown key	Check the Authorization header
403	forbidden	Key lacks the scope for this endpoint	Request a key with the right scope
404	not_found	No such swap / webhook / route	Check the id
409	conflict	Idempotency-Key reused on a different request, or swap already submitted with another tx	Use a fresh key / don't resubmit
429	rate_limited	Over your rate limit	Back off; see Retry-After
502	upstream_error	A chain RPC or the subgraph was unreachable	Retry with backoff
500	internal	Something broke on our side	Retry; if it persists, send us the request_id

Handling tips

• Treat 429 and 502 as transient — retry with exponential backoff and jitter.
• Treat 400, 403, 404, 409 as your bug — don't blind-retry, fix the request.
• A 200 with "fillable": false on POST /v1/swaps is not an error — it means no liquidity right now.