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
{
"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. ForINVALID_PARAMETERS, it isInvalid indicator parameterswhen the problems are inparams; 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: forINVALID_PARAMETERS, the list of problems.pathis a JSON Pointer from the root of the request body (/from,/params/minimum,/instruments/0), missing and unknown fields included (/params/colourabove), 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:/idfor the key id ofDELETE /v1/keys/{id}orPOST /v1/keys/{id}/rotate. For a value outside a list,messagegives the accepted values (must be one of "live", "confirmed");instance: the unique id of the request (a UUID), to share with 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). 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).
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.
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).
{"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.
Code reference
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
INVALID_PARAMETERSInvalid 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_INDICATORUnknown indicator | 404 | This indicator does not exist. | Check the id in the catalog (GET /v1/indicators). |
UNKNOWN_INSTRUMENTUnknown instrument | 404 | This instrument is not available. | Check the symbol with GET /v1/instruments (case-sensitive). |
NOT_COVEREDRange 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_EXCEEDEDQuota 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_LIMITEDRate 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. |
CAPACITYCapacity reached | 503 | The service is temporarily at capacity. | Retry with exponential backoff. |
CURSOR_EXPIREDCursor 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. |
UNAUTHORIZEDUnauthorized | 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. |
FORBIDDENForbidden | 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_FOUNDNot found | 404 | Unknown URL, or the key does not exist. | Check the URL and the id. |
METHOD_NOT_ALLOWEDMethod 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. |
CONFLICTConflict | 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_DOWNSource 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_ERRORUpstream error | 502 | A temporary incident on our side. | Retry with exponential backoff. |
INTERNALInternal 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.