Reference

Errors

The error envelope and every error code.

FomoData uses conventional HTTP status codes and one JSON error envelope for every failure. Branch on the machine-readable code, not on the message text.

Error format

422 Unprocessable EntityJSON

{
  "error": {
    "type": "invalid_request",
    "code": "INVALID_TOKEN",
    "message": "Token could not be resolved.",
    "request_id": "req_6Yq1Hn0bVx3LmT8sRk2Wc4",
    "param": "token",
    "doc_url": "https://fomodata.dev/docs/errors#invalid_token"
  }
}

Field	Description
`type`	Broad category, listed below.
`code`	Specific, stable error code. Safe to branch on.
`message`	Human-readable explanation. May change; don't parse it.
`request_id`	Same as the `X-FomoData-Request-Id` header.
`param`	The offending parameter, when there is one.
`details`	Extra structured data, e.g. validation issues or `AMBIGUOUS_TOKEN` candidates.
`doc_url`	A link to this page, anchored to the code.

HTTP status codes

Status	Meaning
200 / 201	Success / created.
400	Malformed request, invalid cursor, test-only endpoint called with a live key.
401	Missing, invalid, revoked or expired API key.
403	Insufficient scope, live access not approved, history limit, archived project, webhook endpoint limit (WEBHOOK_LIMIT_REACHED).
404	Not found, or the feature is disabled.
409	Conflict, e.g. an ambiguous token symbol.
422	Validation failed.
429	Rate limit, monthly quota or stream connection limit.
500	Internal error.
502	The upstream returned an invalid response.
503	The upstream is unavailable (circuit open) or upstream capacity is exhausted.

Error types

Type	What to do
`invalid_request`	Fix the request. Retrying unchanged will fail again.
`authentication_error`	Check the key: present, correct, not revoked or expired.
`permission_error`	The key is valid but not allowed to do this (scope, live approval, history window, archived project, plan webhook limit).
`not_found`	The object doesn't exist, or the feature isn't available on this deployment.
`conflict`	The request is ambiguous or conflicts with current state. Read details and resend.
`rate_limit`	Slow down. Retry after the Retry-After header or X-RateLimit-Reset.
`api_error`	Our fault. Safe to retry with backoff; include the request id if it persists.
`upstream_error`	The upstream Fomo data source returned something invalid. Retry with backoff.
`upstream_unavailable`	The upstream is unavailable or capacity is exhausted. Retry after Retry-After; cached data may still be served elsewhere.

Error codes

Each code has an anchor, so doc_url lands right on its row.

VALIDATION_FAILED422invalid_request
The request failed validation.
INVALID_REQUEST400invalid_request
The request is malformed.
INVALID_CURSOR400invalid_request
The pagination cursor is invalid or expired.
INVALID_TOKEN422invalid_request
Token could not be resolved.
INVALID_HANDLE422invalid_request
The handle is not a valid Fomo handle.
INVALID_TIME_WINDOW422invalid_request
created_after must be before created_before.
WEBHOOK_URL_FORBIDDEN422invalid_request
This webhook URL is not allowed.
TEST_MODE_ONLY400invalid_request
This endpoint is only available with a test key.
PAYLOAD_TOO_LARGE413invalid_request
The request body is too large.
MISSING_API_KEY401authentication_error
No API key provided. Use 'Authorization: Bearer fd_…'.
INVALID_API_KEY401authentication_error
The API key is invalid.
API_KEY_REVOKED401authentication_error
The API key has been revoked.
API_KEY_EXPIRED401authentication_error
The API key has expired.
INSUFFICIENT_SCOPE403permission_error
The API key does not have the required scope.
LIVE_ACCESS_NOT_APPROVED403permission_error
This project is not approved for live data.
HISTORY_LIMIT403permission_error
The requested window is older than your plan's history limit.
PROJECT_ARCHIVED403permission_error
The project for this key is archived.
WEBHOOK_LIMIT_REACHED403permission_error
This project has reached its plan's webhook endpoint limit for this environment.
FEATURE_DISABLED404not_found
This feature is not available.
NOT_FOUND404not_found
The requested resource does not exist.
PROFILE_NOT_FOUND404not_found
No Fomo profile matches that reference.
THESIS_NOT_FOUND404not_found
No thesis matches that id.
TOKEN_NOT_FOUND404not_found
No token matches that reference.
EVENT_NOT_FOUND404not_found
No event matches that id.
WEBHOOK_NOT_FOUND404not_found
No webhook matches that id.
DELIVERY_NOT_FOUND404not_found
No webhook delivery matches that id.
AMBIGUOUS_TOKEN409conflict
More than one token matches that symbol. Pass a chain or use the token id/address.
CONFLICT409conflict
The request conflicts with the current state.
RATE_LIMITED429rate_limit
Too many requests. Slow down and retry after the reset time.
QUOTA_EXCEEDED429rate_limit
Monthly request quota exhausted for this plan.
STREAM_CONNECTION_LIMIT429rate_limit
Too many concurrent stream connections for this plan.
INTERNAL_ERROR500api_error
Something went wrong on our side.
UPSTREAM_ERROR502upstream_error
The upstream Fomo data source returned an invalid response.
UPSTREAM_UNAVAILABLE503upstream_unavailable
The upstream Fomo data source is unavailable. Try again shortly.
UPSTREAM_BUDGET_EXHAUSTED503upstream_unavailable
Upstream capacity is temporarily exhausted; only cached data can be served.

Retrying safely

Retry 429, 500, 502 and 503 with exponential backoff and jitter. Always honour Retry-After when present.
Don't retry other 4xx responses unchanged; they will fail the same way.
QUOTA_EXCEEDED won't clear until your monthly quota resets or you upgrade.