Errors

v1 is closed to new integrations

Do not build on v1. The current API is v2 RFQ. v1 stays served for integrations already running on it, takes no new features, and gets no new endpoints.

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.