Reference
Errors
One error envelope on every endpoint and in every MCP tool’s error result, with a stable code for each failure.
Error envelope
The same shape on every status code from 400 upward.
{
"error": "invalid_query",
"message": "Unknown signal rsi_99. It is not a published signal. Did you mean rsi_14 or rsi_7? Catalog: /v2/signals",
"request_id": "req_9f2b8a1c03d4e5f6a7b8"
}Envelope fields
Every response, success or error, carries the same id in the X-Tickerbot-Request-Id header. Include it when you contact support: it points us at your exact request.
| Field | Meaning |
|---|---|
error | The stable code, from the table below. |
message | What went wrong, in words, with the fix where there is one. |
request_id | This request’s id, the same as the X-Tickerbot-Request-Id header. |
code, plan, upgrade_url | Plan-limit errors only (the 429 rate limit, the Free 402 quota, webhook and stream limits): code repeats error, plan is your plan, upgrade_url is where to raise the limit. |
Error codes
Stable, machine-readable codes. The HTTP status is set accordingly.
| Code | Status | When you see it |
|---|---|---|
bad_ | 400 | The request was malformed: missing required parameter, invalid format, value out of range or unsupported combination, such as two names of one param at once with different values, its current name and an older one or two older ones (the same value under both is accepted; see Deprecations › Still accepted), or a cursor sent with params that differ from the page that returned it (the message names the param; see Pagination). A date param (from, to, asof, …) that is not a real date, such as 2026-02-30, answers this with the param, the value and the format; so does a date before 1900, and a timestamp with a UTC offset (+02:00), where the message asks for Z (UTC).Emitted by: GET /v2/tickers/{ticker}/coverage, POST /v2/tickers/{ticker}/subscribe, GET /v2/signals, POST /v2/signals/{signal}/subscribe, POST /v2/signals, PATCH /v2/signals/{signal}, POST /v2/scan, POST /v2/scan/subscribe, GET /v2/news, POST /v2/news/subscribe, POST /v2/universes, POST /v2/events/subscribe |
compile_ | 400 | A custom signal's expr failed to compile against the catalog. The response carries message (the first problem, and how many more there are) and a structured errors array, one entry per problem with code, message, optional pos (character offset) and an optional suggestion. |
context_ | 400 | The qualifier case-folds to two different catalog symbols (the preferred-share spellings: ADSW and ADSw are different instruments). Type the exact symbol. |
context_ | 400 | A q used the qualified context-ticker syntax (spy.sma_50) with an index series we recognize but do not carry (vix and dxy). Any symbol in the catalog can be a context ticker; a symbol that is not in it is unknown_context_ticker below. |
device_ | 400 | A webhook create or update with channel=mobile_push referenced a device_id that is not registered to your account. Device registrations are per-account: one account cannot route pushes to another's phone. Re-register via POST /v2/devices/register and retry with the returned id. |
expanded_ | 400 | Your q is within the 4,000-character limit, but after custom-signal references were expanded into their SQL it exceeded the 100,000-character execution bound. Distinct from bad_request ("your query is too long"): this means "your query expands too much". Simplify the referenced custom signals or reduce nesting. |
interval_ | 400 | The requested signals cannot be served at the requested grain: a pinned grain on an as-of read (scan, Get a signal, Get a ticker) that does not store a signal you named, or that needs an intraday asof; select=* on scan with a non-daily grain (only 1d stores every signal; 1m/1h carry a subset); join=state on events, or a kind=signal read, naming a signal not stored at that grain. The message lists where each missing one is available. Name the signals you need with select, or request the grain that carries them. On Get a ticker with asof and a pinned grain, it is a 404 when the ticker has no data at that grain within the grain's window before the instant (14 days for 1d, 5 for 1h/1m; the 1m grain covers only the most liquid tickers); try a coarser grain or grain=auto. From 2027-01-12 this code is grain_unavailable, with the same status and message (listed under Deprecations); match both until then. |
invalid_ | 400 | The q clause failed to parse, references an unknown signal or uses a disallowed SQL feature (semicolons, comments, INSERT/UPDATE keywords). The message is written for the reader: an unknown signal names the nearest live ones and points at the catalog; a bare numeric or text signal where a condition is needed, or a true/false signal compared to a number, says what to write instead. |
not_ | 400 | A kind=signal events read named a numeric signal. Only booleans have firings; a numeric like rsi_14 has none. The message points at /v2/tickers/{ticker}/history for the value series.Emitted by: GET /v2/events |
not_ | 400 | A grammar param was used on an event kind that cannot serve it unscoped (today only kind=signal). There, q and join=state require signal=<name>, which binds the query to an index instead of scanning. group_by is unavailable there entirely: an aggregate has no limit to stop at, so it reads every firing in the window whatever you name, which is also why a mixed kind list containing signal is refused. Filter mode (kind/ticker/universe/from/to/limit) needs none of this and is always open.Emitted by: GET /v2/events |
too_ | 400 | An account-level ceiling on how many custom signals one account may author. Like too_many_universes, this is an anti-abuse guard rather than a plan limit: custom signals are unlimited on every plan including Free, and upgrading does not raise this ceiling.Emitted by: POST /v2/signals |
too_ | 400 | An account-level ceiling on how many universes one account may hold (1,000). It is an anti-abuse guard, not a plan limit: the same on every plan including Free, and upgrading does not raise it. Only universes you created count; the built-in ones ( top_10, top_100) are exempt. Delete some to create more.Emitted by: POST /v2/universes |
universe_ | 400 | A subscribe (or a webhook update) named a universe that is neither a built-in universe (top_10, top_100) nor one your account owns, so the webhook could never fire. Slugs are account-scoped, so another customer's universe reads as missing, not forbidden. A read (Scan, Get a signal, Query events, Query news) never fails on it: it answers 200 with no results and the id in not_found. |
unknown_ | 400 | A q (scan or webhook) referenced <ticker>.<signal> with a symbol that is not in the catalog. Checked before the query runs, so a typo names itself instead of returning zero results. Spell the symbol as /v2/tickers returns it; dotted symbols such as BRK.B cannot be qualifiers because the dot is the separator. |
unknown_ | 400 | The request carried a query or body parameter name the endpoint does not accept: usually a typo ( tickr) or a param that belongs to a different endpoint. The message lists the query and body parameters the endpoint takes for the method you called, by their current names. A parameter the path takes only on another method (tickers on GET /v2/universes, a Create field) is ignored until 2027-01-12 and answers this error from then (Deprecations). The websocket stream answers a subscribe or unsubscribe frame key that names another param (a list of signals, symbols, asof) with an error frame of this code, naming the key and what to send instead.Emitted by: Every endpoint |
unknown_ | 400 | A universe POST/PATCH referenced symbols we do not track, or that are no longer active. The message names the offenders (up to ten) and disallowed carries the full list. |
unauthenticated | 401 | The Authorization header is missing, malformed or carries a key that has been revoked or never existed. API keys are passed as Authorization: Bearer tb_(test|live)_<key>.Emitted by: Every endpoint |
monthly_ | 402 | The Free plan's monthly call quota (10,000 calls per calendar month, UTC) is used up. The quota resets on the 1st; resets_at carries the exact instant. Paid plans have no monthly cap. Rejected requests (429s and this error) and server-side 5xx errors never consume quota. |
system_ | 403 | A write ( PATCH/DELETE) targeted a built-in universe (top_10, top_100). Built-in universes are read-only: copy the constituents into a universe of your own to customize. |
webhook_ | 403 | You've hit the maximum number of webhook subscriptions your plan allows. Delete an inactive one or upgrade to add another. The message names the next tier's cap. |
webhook_ | 403 | Re-enabling a webhook is refused because the account holds more than the plan allows, typically after a downgrade left it over cap (on Free, any webhook is over a cap of 0). Distinct from webhook_limit_reached, which guards creating one. Delete webhooks to get within the limit, or upgrade.Emitted by: PATCH /v2/webhooks/{webhook} |
webhook_ | 403 | You tried to create a webhook on a plan that does not include them (the Free plan today). Webhooks start on the first paid tier (Hobby, at 10 of them), and the body carries an upgrade_url straight to billing. |
not_ | 404 | The requested resource (ticker, webhook, delivery) does not exist or is not accessible to your API key, or the URL path itself is not a route. Only one thing named in the path answers it (one ticker, one signal, one universe, one webhook): a list of things in the path or a parameter never does. A read lists the unknown ones in not_found with a 200, even when that is all of them; a subscribe or webhook update refuses them with a 400 naming them. Unknown-path 404s always carry docs_url (the API reference), and when the wrong path is a recognized near-miss of a real route they also carry suggestion: the route you probably meant, e.g. GET /v2/bars → /v2/tickers/{ticker}/bars/{interval}. If your client sees suggestion, switch to that route; retrying the same path will 404 forever.Emitted by: GET /v2/tickers/{ticker}, GET /v2/tickers/{ticker}/bars/{interval}, GET /v2/tickers/{ticker}/coverage, GET /v2/tickers/{ticker}/holdings, POST /v2/tickers/{ticker}/subscribe, GET /v2/signals/{signal}, PATCH /v2/signals/{signal}, DELETE /v2/signals/{signal}, GET /v2/universes/{universe}, PATCH /v2/universes/{universe}, DELETE /v2/universes/{universe}, GET /v2/tickers/{ticker}/history |
unknown_ | 404 | The signal name in the path is not a signal. Check the signal catalog for valid names. |
already_ | 409 | A custom-signal POST (or PATCH rename) used a name you already own. Distinct from name_collision, which fires when the name clashes with a built-in signal. Pick a different name, or PATCH the existing signal. |
delivery_ | 409 | A delivery resend was refused because that delivery is still being retried. Resend it once it has delivered or failed (its status on the deliveries route). |
idempotency_ | 409 | A request carrying the same Idempotency-Key is still being processed. Retry after it completes: the finished response will replay (with an Idempotency-Replayed: true header) instead of creating a duplicate. Applies to the create endpoints (webhook creates and subscribes, custom signals, universes). |
name_ | 409 | A custom signal POST (or PATCH rename) was rejected because the chosen name is a built-in signal. Built-ins win: rename your signal. A clash with another of your own custom signals returns already_exists instead. |
rename_ | 409 | A custom-signal PATCH rename was refused because other custom signals reference the old name; renaming would break their compilation. Carries references.signals. Edit those references first, or delete and recreate.Emitted by: PATCH /v2/signals/{signal} |
signal_ | 409 | A DELETE /v2/signals/{signal} was refused because another custom signal references the deleted name. The response carries a referencing_signals array so you can audit before forcing. Pass ?force=true to delete anyway; downstream references will fail compilation until you fix them.Emitted by: DELETE /v2/signals/{signal} |
slug_ | 409 | A POST tried to create a universe with a slug that already exists in your account. Emitted by: POST /v2/universes |
universe_ | 409 | A universe DELETE was refused because webhooks still reference it. Carries referencing_webhooks (id + name). Delete those webhooks first, or pass ?force=true to delete anyway; a forced delete disables them at their next evaluation. Mirrors the custom-signal delete contract (signal_referenced).Emitted by: DELETE /v2/universes/{universe} |
webhook_ | 409 | A delivery resend ( POST /v2/webhooks/{webhook}/deliveries/{delivery}/redeliver) was refused because the webhook is disabled. Turn it back on (PATCH /v2/webhooks/{webhook} with enabled: true), then resend. |
gone | 410 | The route was removed: 410 (not 404) so the removal is a stated fact to any remaining caller, and the message says what replaced it. The removed routes are listed under Deprecations › Retired. |
idempotency_ | 422 | An Idempotency-Key was reused for a different request than the one that minted it: a different method or path, or the same path with a different body (compared as JSON, so key order does not matter and a key sent as null counts as not sent). A key is only valid for replaying the exact request it was first sent with; replaying it for another request would hand back an object that request did not create. Use a fresh key per distinct request. |
dashboard_ | 429 | Returned by the dashboard's tool tabs (Tickers, Signals, Scan, Universes, Webhooks), never by a call made with an API key. Those tabs refresh on their own and do not count toward the monthly quota, so each account has a daily cap of 10,000 of their calls instead, resetting at 00:00 UTC. Working interactively stays far below it; it stops a script from driving the dashboard instead of the API. Programs use an API key. |
rate_ | 429 | You exceeded your plan's per-minute request limit. The Retry-After header gives the seconds until your oldest request ages out of the rolling window (at most 60). The body names your plan's limit and the tier that raises it.Emitted by: Every endpoint |
sandbox_ | 429 | The no-key sandbox ( /v2/sandbox/*) is the same API with the same responses; without a key it is budgeted per IP at 30 requests/hour and 60/day. Carries limits and retry_after_seconds in the body, plus Retry-After, X-Sandbox-Remaining-Hour and X-Sandbox-Remaining-Day headers (the two X-Sandbox-Remaining-* headers also ride on every successful anonymous sandbox response, so you can watch the budget before hitting it). Signed in on the docs, or with an API key on /v2, your plan's per-minute limit applies instead. |
too_ | 429 | Failed-auth flood gate: 30 or more failed authentication attempts in a minute from one IP are refused before key lookup, with Retry-After: 60. Successful auths never count toward the gate, so shared IPs with real traffic are unaffected. Fix the key you are sending rather than retrying it. |
internal | 500 | Something went wrong on our side. Safe to retry with exponential backoff. Include the failing request and timestamp if you contact support. Emitted by: Every endpoint |
upstream_ | 502 | Operational and transient: an image endpoint ( GET /v2/tickers/{ticker}/icon, /logo) could not fetch the image from its source. Retry shortly; the ticker and every other endpoint are unaffected. |
index_ | 503 | A composite index needed for a list query is still building (typically <1 minute on initial deploy). Your query and data are fine; only the index is missing, so retry shortly rather than changing the request. |
kind_ | 503 | An event kind is provisioned but its database support is not in place (operational and transient; today only kind=signal can emit it). Retry later or drop the kind from the request; not a plan or validation error.Emitted by: GET /v2/events |
unavailable | 503 | Operational and transient; retry, do not change the request. On /v2/tickers/{ticker}/bars/{interval} it means the bars for a sub-hour or 1s read could not be loaded right now (the response carries Retry-After, in seconds), never an empty or stale page. On /v2/events it means signal firings are briefly unavailable, or that a kind=signal read could not read the next stretch of history in time three pages in a row (retry the same cursor). On any endpoint that runs a database query it means the query ran past the 30-second limit or could not get a database connection; the response carries Retry-After (seconds). The first read of a historical date is the slow one, so a retry of the same request usually answers in seconds. Not a validation or plan error. |
DELETE endpoints return 204 No Content on success: no body to parse, check the status code. Their errors still come back in the envelope above.
Which errors to retry
Some failures clear on their own; others fail the same way every time.
- Retry
internal(500) and every502/503(unavailable,upstream_unavailable,index_building,kind_unavailable) with exponential backoff, starting at 1 second and doubling, capped at 60 seconds. - Don't retry
bad_request(400),invalid_query(400) orunauthenticated(401): the same request fails the same way. Fix it first. - A
429carries its own wait: see Rate limits.
Retired codes
No current endpoint returns these. They're listed for integrations that still branch on them.
expression_invalid_at_interval(400): Retired 2026-11-10 with the signal history route: it answered a custom signal at a grain that lacks one of its signals. Current reads answerinterval_unavailable.kind_not_subscribable(400): Retired 2026-07-27. A kind Subscribe to events does not take is a 400bad_requestnaming the subscribable kinds.not_supported_for_custom_signal(400): Retired 2026-11-11:kind=signalon Query events reads a custom signal's flips like a built-in's, computed when you ask. It answered a custom-signal name there.recursion_depth_exceeded(400): Never emitted: a custom-signal chain more than 5 levels deep fails ascompile_failed, with the sub-errorforbidden_syntax.signal_not_available_at_interval(400): Retired 2026-11-10 with the signal history route: it answered a1hor1mrequest for a daily-only signal. Current reads answerinterval_unavailable.subscription_required(402): Retired 2026-07-18: a valid key is never refused for lack of a subscription; without one it runs on Free.asof_tier_required(403): Retired 2026-07-31:asofhas unlimited depth on every plan.plan_required(403): Retired 2026-07-31:join=stateon events is on every plan.resource_limit_reached(403): Retired: each cap returns its own code (webhook_limit_reached,webhook_tier_required,too_many_universes,too_many_custom_signals).channel_not_implemented(501): Retired 2026-11-10: it answeredchannel: "slack". Slack delivery was retired, so that request is now a400 bad_requestsaying so; usewebhookordiscord.