Errors and retries

Error responses

Core API errors use a problem response, such as the validation example below. Gateway authentication failures and Circle Gateway deposit-address errors can use other envelopes; inspect the HTTP status as well as the body.

{
  "type": "https://api.eco.com/v1/errors/slippage-out-of-bounds",
  "title": "slippage is outside the valid 0.0001-1 range; it is a decimal fraction (0.005 = 0.5%), not a percent (0.5 means 50%)",
  "status": 400,
  "code": "slippage-out-of-bounds",
  "detail": "slippage: slippage is outside the valid 0.0001-1 range (error code: slippage-out-of-bounds)",
  "errors": [{ "field": "slippage", "detail": "slippage is outside the valid 0.0001-1 range; it is a decimal fraction (0.005 = 0.5%), not a percent (0.5 means 50%)" }],
  "requestId": "1132eab2-a0e8-4308-b0d0-d99a998997cc"
}

What each status means

HTTP	Codes	Handling
`400`	`invalid-request`, `invalid-parameter`, `missing-parameter`, `slippage-out-of-bounds`	Fix the field named in `errors`: nesting (`funder` belongs in `source`), a missing `type` or `dappId`, address format, units, a `quoteId` sent with its `quote:` prefix, or `limit` above 50. Do not retry unchanged.
`401`	`invalid-api-key`, `api-key-expired`, `invalid-signature`, `authorization-expired`	`invalid-api-key` without `detail`: the supplied key is unknown, revoked, or not enabled for v1; returned on every endpoint, including ones that work without a key. With `detail` “could not be attributed” on a submit endpoint: the key is valid but not yet mapped to a partner; contact Eco. Signature codes need a fresh signature. Do not retry unchanged.
`403`	Gateway `{"Message": …}` (no code), `permission-denied`, `funder-mismatch`	On a required endpoint without a key: add the key. Otherwise the key lacks permission, or the signer does not match the funder.
`404`	`endpoint-not-found`, `token-not-found`	Check the path. Note that valid intent/job status lookups report an unknown ID as `status: "unknown"` with `200`. A Circle Gateway deposit lookup can return `404`. Unknown paths under `/v1` may return the gateway `403` instead.
`409`	`signature-already-bound`, `nonce-used`	The signature or nonce was already used. Look up the original job before signing again.
`410`	`quote-expired`	Request a fresh quote. Quotes are short-lived; read `expiresAt`.
`422`	`chain-not-supported`, `no-route-found`, `chain-pair-unsupported`, `amount-too-low`, `amount-too-high`, `insufficient-liquidity`, `simulation-failed`	The request cannot be fulfilled as submitted. Use the reported reason to change it. An unsupported chain returns `chain-not-supported`; other unfillable routes still surface as `502 solver-error` (see below).
`429`	`rate-limit-exceeded`	Back off. Honor `Retry-After` when present.
`500`, `502`, `503`	`internal-error`, `solver-error`, `solver-timeout`, `service-unavailable`	For reads and quotes: bounded retry with backoff. For submits: resend the identical signed payload to the same endpoint; the API returns the existing job with `200` rather than creating a second one.

A quote 502 does not identify one cause. POST /v1/quotes answers 502 solver-error when no solver returns a usable quote: tokens that are not in GET /v1/tokens, pairs with no available liquidity, amounts no solver can fill, and upstream solver failures or timeouts. Check the pair against GET /v1/tokens; for retryable failures, use a bounded retry budget. No requests-per-second quota is published. Do not assume a fixed allowance from the absence of 429 responses. The full code catalog is in the OpenAPI document under x-error-catalog; an individual endpoint may expose only a subset.

Conventions

Discovery and quotes

Quote funding and status

Circle Gateway fast deposits

Open quoting service

Errors and retries

Error responses

What each status means

​Error responses

​What each status means

Error responses

What each status means