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

Errors are returned in the following format:

```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 status lookups never return `404`; an unknown ID reports `status: "unknown"` with `200`. 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` | Every solver rejected the request for a stated reason. Change the request. 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.                                                                                                                                                           |

**`502` on a quote is usually not an outage.** `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 cold routes that take longer than the quote budget. Check the pair against `GET /v1/tokens`; if it is listed, retry a moment later.

The full code catalog is in the [OpenAPI document](/api-v1.openapi.json) under `x-error-catalog`.