Errors and Security

Error shape

Errors are flat JSON objects:

{
  "error": "amount must be greater than 0"
}

Log error strings on your backend. Show user-friendly copy in your UI.

Status handling

Status	Meaning	Client action
`400`	Invalid request body or unsupported token pair	Fix validation; do not retry unchanged
`401`	Missing or invalid API key	Check backend credential configuration
`404`	Quote, asset, or endpoint not found	Refresh state or request a new quote
`422`	Amount outside accepted limits, when returned	Update UI bounds and ask the user to revise
`429`	Rate limited, when returned	Back off with jitter server-side
`500`	Unexpected service error	Retry later with a fresh quote
`503`	Quoting temporarily unavailable	Disable execution UI and retry later

Retry rules

Retry 429, 500, and 503 with exponential backoff.
Do not retry unchanged 400, 401, 404, or 422 requests.
Never submit a transaction from an expired firm quote.
Request a new firm quote after any wallet preparation or signing error.

Public/private boundary

Partner-facing responses intentionally expose only the fields required to price, display, and submit a quote. Internal economics, provider diagnostics, operator controls, and route selection details stay outside the public API.

The public transaction packet is enough for wallet submission: to, data, value, and chain_id.