# Errors

Every error carries a `code`, the same over REST and the WebSocket. Build your logic on that code: the message text may change, the code never will.

> **`402` does not ask for a payment.** The API answers `402 NOT_COVERED` when the data does not exist: a day not over yet, or a range before the start of our history. Buying a plan does not change it. A request your plan or your key does not cover is a `403 FORBIDDEN`. HTTP clients, proxies and monitoring tools read `402` as "Payment Required": handle it by its `code`.

## Over REST

```json
{
  "type": "https://fathomcharts.com/docs/errors#invalid-parameters",
  "title": "Invalid parameters",
  "status": 400,
  "detail": "Invalid indicator parameters",
  "code": "INVALID_PARAMETERS",
  "instance": "0f8e2c4a-6b1d-4e57-9a3c-2d7f5b8e1a64",
  "errors": [
    { "path": "/params/colour", "message": "is not a parameter of this indicator" },
    { "path": "/params/minimum", "message": "must be >= 1" }
  ]
}
```

- `code`: the error code, listed below;
- `detail`: a human-readable explanation. For `INVALID_PARAMETERS`, it is `Invalid indicator parameters` when the problems are in `params`; otherwise it lists each problem as `<field> <message>`, separated by `; ` (`to is required`, `limit is not a field of this request`, `from must be Unix nanoseconds, from 1000000000000000000 to 18446744073709551615`);
- `errors`: for `INVALID_PARAMETERS`, the list of problems. `path` is a JSON Pointer from the root of the request body (`/from`, `/params/minimum`, `/instruments/0`), missing and unknown fields included (`/params/colour` above), as well as rules that tie several fields together; it is `/` when the body is not a JSON object. A path parameter that is not valid appears under its name: `/id` for the key id of `DELETE /v1/keys/{id}` or `POST /v1/keys/{id}/rotate`. For a value outside a list, `message` gives the accepted values (`must be one of "live", "confirmed"`);
- `instance`: the unique id of the request (a UUID), to share with [support](#support) if needed.

When a history query or an export exceeds your budget, the response also gives its cost (`computeUnits`) and what you have left (`remainingComputeUnits`). `429` and `503` responses carry a `Retry-After` header: the number of seconds to wait. `413` and `415` responses (body too large, `Content-Type` other than `application/json`) have no `errors` field. `401` responses carry a `WWW-Authenticate` header (see [Authentication](https://fathomcharts.com/docs/authentication.md#api-keys)). An HTTP method that does not exist for a known path is rejected with `405 METHOD_NOT_ALLOWED`, and the `Allow` header lists the accepted methods.

`402 NOT_COVERED` and `403 FORBIDDEN` look alike but mean different things: `402` means the data does not exist (a day not over yet, a range before the start of our history); `403`, that your plan or your key does not cover the request (history depth, delayed data, missing plan or scope).

Every error of the API is an `application/problem+json` document. A response in `text/plain` (a body such as `error code: 502`) comes from the network in front of the API, not from the API: it has no `code`. Handle it by its HTTP status, a `5xx` as a temporary failure (see [Rules for your REST client](https://fathomcharts.com/docs/maintenance.md#rules-for-your-rest-client)).

Every endpoint, its responses and its error codes are described in the OpenAPI 3.1 description of the API: [`https://api.fathomcharts.com/docs/json`](https://api.fathomcharts.com/docs/json).

## Over the WebSocket

A refused or interrupted subscription receives an `error` message with its `sub`. Only that subscription is closed: the connection and your other subscriptions keep running. Refusals (parameters, rights, quotas) arrive before `subscribed`; after `subscribed`, an error can still close the subscription, for example `NOT_COVERED` when the computation needs history older than our data (see [Refusals and errors](https://fathomcharts.com/docs/websocket.md#refusals-and-errors)).

```json
{"sub":"bt","t":"error","code":"UNKNOWN_INDICATOR","message":"unknown indicator `big-trade`"}
```

A message the server does not understand (invalid JSON, unknown type, missing or unreadable `sub`) receives an `INVALID_PARAMETERS` `error` without `sub`. A `subscribe` or `unsubscribe` whose `sub` can be read but which is otherwise invalid (unknown field, malformed `mode` or `from`…) receives the `error` with that `sub`. Such an `error` does not close the active subscription of that `sub`, if there is one: an invalid `unsubscribe` leaves it running. A `subscribe` whose `sub` is already taken on the connection receives an `error` without `sub`: the active subscription of that name carries on.

With the SDK, a subscription error ends its loop with the SDK’s error, carrying the received `code`.

Problems that close the whole connection (key rejected, too many connections, client too slow, invalid frames, too many messages) do not come as `error` messages but as [close codes](https://fathomcharts.com/docs/websocket.md#closing-and-reconnecting).

## Code reference

| Code                                      | HTTP            | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | What to do                                                                                                                                                                          |
| ----------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INVALID_PARAMETERS` (Invalid parameters) | 400 · 413 · 415 | Invalid request: a field is unknown, missing, of the wrong type or out of range, a page cursor (`next`) does not belong to this query, or the body is empty or not valid JSON (`400`, `path: "/"` for the body); the body is over 16 KiB, that is 16,384 bytes (`413`); a missing or non-`application/json` `Content-Type` on a non-empty body (`415`). `413` and `415` responses have no `errors` field. On the WebSocket: an invalid message or `subscribe` (unknown field, malformed `mode` or `from`, a `from.time` not in nanoseconds, in the future or within the delay, a `sub` already in use), refused before `subscribed`. | Fix the request. The `errors` field lists each problem and where it is (`path`, a JSON Pointer from the root of the body, for example `/params/minimum`).                           |
| `UNKNOWN_INDICATOR` (Unknown indicator)   | 404             | This indicator does not exist.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Check the id in the catalog (`GET /v1/indicators`).                                                                                                                                 |
| `UNKNOWN_INSTRUMENT` (Unknown instrument) | 404             | This instrument is not available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Check the symbol with `GET /v1/instruments` (case-sensitive).                                                                                                                       |
| `NOT_COVERED` (Range not covered)         | 402             | The data is not available for all or part of the range: a day that is not over yet, or before the start of our history. It is not a matter of plan (see `FORBIDDEN`). On the WebSocket: the computation needs history older than our data (for example `key-levels` with many `days` or `weeks`).                                                                                                                                                                                                                                                                                                                                    | Narrow the range. The estimate lists the days involved (`missingDays`) and the message gives the limit served. On the WebSocket, lower the parameters that reach far into the past. |
| `QUOTA_EXCEEDED` (Quota exceeded)         | 429 · 409       | You hit a limit of your plan: the monthly compute budget or export volume (`429`), the number of subscriptions or custom configurations (WebSocket), or 10 valid keys, `active` or `expiring` (`409`).                                                                                                                                                                                                                                                                                                                                                                                                                               | Check `GET /v1/usage`. Narrow the range, wait for next month (`Retry-After`), close a subscription or revoke a key.                                                                 |
| `RATE_LIMITED` (Rate limited)             | 429             | Too many requests in a short time: REST requests of your account, history requests running at the same time, sign-in links requested for an email address, or questions sent from the site. On the WebSocket, too many messages close the connection (code `1008`).                                                                                                                                                                                                                                                                                                                                                                  | Wait for the number of seconds given in `Retry-After`.                                                                                                                              |
| `CAPACITY` (Capacity reached)             | 503             | The service is temporarily at capacity.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Retry with exponential backoff.                                                                                                                                                     |
| `CURSOR_EXPIRED` (Cursor expired)         | 410             | The next-page cursor (`next`), or the export being resumed, comes from before an update to how the indicator is computed. Unrelated to the WebSocket `cursor_expired` `reset`.                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Run the query or the export again from the start, dropping what you already received.                                                                                               |
| `UNAUTHORIZED` (Unauthorized)             | 401             | The key or token is missing, invalid, expired or revoked, or the sign-in link has expired or was already used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Check the `Authorization` header (`Bearer <key>`), or request a new token or a new link. Over REST, the response carries a `WWW-Authenticate` header.                               |
| `FORBIDDEN` (Forbidden)                   | 403             | You are authenticated but not allowed to access what you asked for: the key lacks a scope, the instrument or IP address is not allowed, an attempt to manage a key that has more rights than the key you use, or your plan does not cover the request (no history, or not that far back; delayed data). The data exists (otherwise: `NOT_COVERED`).                                                                                                                                                                                                                                                                                  | The message says what is missing: adjust the key or add the plan you need.                                                                                                          |
| `NOT_FOUND` (Not found)                   | 404             | Unknown URL, or the key does not exist.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Check the URL and the id.                                                                                                                                                           |
| `METHOD_NOT_ALLOWED` (Method not allowed) | 405             | This path exists, but not with this HTTP method (a `GET` on a `POST` endpoint, for example).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Use one of the methods listed in the `Allow` header of the response.                                                                                                                |
| `CONFLICT` (Conflict)                     | 409             | The action is not possible in the current state: the key was already rotated, you already own the offer, or the billing country is served by a different payment provider than the account’s.                                                                                                                                                                                                                                                                                                                                                                                                                                        | Check the current state before trying again.                                                                                                                                        |
| `SOURCE_DOWN` (Source down)               | — (WebSocket)   | WebSocket only: the data of this instrument cannot be served for now, and the subscription is closed by this `error`. Not to be confused with the `source_down` `status`, which keeps the subscription open.                                                                                                                                                                                                                                                                                                                                                                                                                         | Retry later. `GET /v1/instruments` reports the state of each instrument.                                                                                                            |
| `UPSTREAM_ERROR` (Upstream error)         | 502             | A temporary incident on our side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Retry with exponential backoff.                                                                                                                                                     |
| `INTERNAL` (Internal error)               | 500             | Something went wrong on our side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Retry. If it persists, write to <support@fathomcharts.com> with the `instance` value of the response.                                                                               |

## Support

An error you do not understand, or an `INTERNAL` error that persists? Write to <support@fathomcharts.com>, with the `instance` value of the response or, on the WebSocket, the time and the `sub` involved.
