Skip to main content

​
The envelope

Swap-domain failures return a machine-readable envelope:
Branch on code, log message for humans. Errors outside the swap taxonomy (auth, validation, rate limits) return { "message": … } without a code: 400 for invalid request bodies, 401 for key/token problems, 404 for unknown resources, 410 for expired quotes, 429 with Retry-After for rate limits.

​
Error codes

The 409 codes are client action required: the request was well-formed, but the wallet needs a one-time setup step before the swap can proceed. The 422 codes mean the swap as specified can’t work: change the request, don’t just retry. The 5xx codes are safe to retry: quoting and building are read-only, and submit is idempotent, so retrying the same submit request returns the existing swap rather than executing twice.

​
Expired quotes and tokens

  • Building with a quote past its 30-second expiresAt → 410 Gone. Re-quote and rebuild.
  • A malformed, tampered, or cross-purpose sealed token (geoQuoteToken where an op token belongs, etc.) → 401; treat it as a bug in token handling, not something to retry.