> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and retries

> How the Eco API reports failures, which errors are safe to retry, and how to handle malformed requests.

## 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.

```json theme={null}
{
  "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](/api-v1.openapi.json) under `x-error-catalog`; an individual endpoint may expose only a subset.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.