Errors

This page covers how errors are shaped and lists every code the API can return, with the endpoints that return it. Use it to decide what to branch on and what to retry.

The error envelope

Every error is JSON with one error object:

{"error":{"code":"invalid_parameter","message":"Invalid or unsupported query parameter: limit."}}

Field	Type	Meaning
`error.code`	string	A stable, machine-readable code. Branch on this.
`error.message`	string	A human-readable explanation. It may change; do not parse it.

Error responses carry Content-Type: application/json; charset=utf-8 and Cache-Control: no-store. Errors after authentication also carry the rate-limit headers; 401 responses carry WWW-Authenticate: Bearer realm="routeur". Successful responses look different: results are wrapped in data, with graph_run on graph-derived responses and next_cursor or next_offset on paginated ones. See Conventions.

Every code

Status	Code	Meaning	Retry
400	`invalid_parameter`	A query parameter is unknown, repeated, malformed or out of range. The message names it. Also returned for a malformed `cursor` and an unknown stream `topics` value.	No; fix the request.
400	`invalid_market`	The venue in the path is not `kalshi` or `polymarket`, the market id is malformed, or the proof endpoint was given the same market twice.	No.
400	`invalid_event`	The venue or event id in an `/v1/events/{venue}/{id}` path is malformed.	No.
400	`invalid_topic`	The topic slug is not lowercase words joined by dashes (up to eight).	No.
400	`invalid_rulebook`	The venue, rulebook kind (`series`, `event`, `market`) or id is malformed.	No.
401	`api_key_required`	No credential was sent.	After adding the key.
401	`invalid_api_key`	The key is malformed, unknown, or its secret does not match.	After a minute if the key was just issued; see revocation lag.
401	`api_key_revoked`	The key was revoked.	No.
401	`invalid_token`	The credential does not start with `rk_` and is not a valid service identity token.	No; check the key’s prefix.
403	`caller_not_allowed`	A valid identity token from an account that may not call the API. Only Routeur’s own services send identity tokens.	No.
404	`not_found`	No such endpoint. Returned without authentication.	No.
404	`market_not_found`	The market is not in the latest graph; on `/rules`, no contract terms have been recorded for it; on the proof endpoint, one or both markets are not in the latest graph.	After the next graph run if the market is newly listed.
404	`event_not_found`	The event is not in the latest graph.	After the next graph run.
404	`topic_not_found`	No listed market is labeled with that name.	No.
404	`relation_not_found`	Both markets are in the graph but no current proof relates their current contract versions.	After the next graph run.
404	`rulebook_not_found`	No such rulebook has been recorded.	No.
404	`book_not_found`	No order book is recorded for the market at that time.	No; try without `at`.
404	`strategy_not_found`	No strategy with that id is supported by settled history right now. Also returned for a malformed strategy id.	Later; the set changes as markets settle.
429	`rate_limited`	The per-minute limit was exceeded.	After `Retry-After` seconds.
429	`daily_quota_exceeded`	The daily quota is used up.	After `Retry-After` seconds.
429	`too_many_streams`	The key already holds its concurrent streams on this instance.	After 60 seconds, or close a stream.
503	`graph_unavailable`	No graph run has finished yet.	After a few minutes.
503	`stream_unavailable`	No stream capacity is free on this instance, or it is shutting down.	After 5 seconds.
503	`database_unavailable`	Only on `/readyz`: the database is not reachable.	Later.
504	`timeout`	The request took longer than 15 seconds.	Once, with a narrower query.
500	`internal`	Something failed on Routeur’s side.	Once, after a short wait.

Only GET is served. Other methods on api.routeur.app are refused before they reach the API, with a non-JSON 403 body.

By endpoint

Every authenticated endpoint can return 401, 429 rate_limited, 429 daily_quota_exceeded, 504 timeout and 500 internal. The table lists what each group adds.

Endpoint	Additional codes
`GET /v1/status`	`503 graph_unavailable`
`GET /v1/openapi.json`	none
`GET /v1/categories`, `/v1/events`, `/v1/search`, `/v1/topics`, `/v1/markets`, `/v1/cross-venue`, `/v1/opportunities`, `/v1/insights`, `/v1/insights/*`, `/v1/flow`	`400 invalid_parameter`, `503 graph_unavailable`
`GET /v1/topics/{slug}`	`400 invalid_topic`, `400 invalid_parameter`, `404 topic_not_found`, `503 graph_unavailable`
`GET /v1/events/{venue}/{id}`, `/related`	`400 invalid_event`, `400 invalid_parameter`, `404 event_not_found`, `503 graph_unavailable`
`GET /v1/markets/{venue}/{id}`, `/relations`, `/related`, `/quotes`, `/trades`	`400 invalid_market`, `400 invalid_parameter`, `404 market_not_found`, `503 graph_unavailable`
`GET /v1/markets/{venue}/{id}/rules`	`400 invalid_market`, `400 invalid_parameter`, `404 market_not_found` (no terms recorded)
`GET /v1/rulebooks/{venue}/{kind}/{id}`	`400 invalid_rulebook`, `400 invalid_parameter`, `404 rulebook_not_found`
`GET /v1/markets/{venue}/{id}/book`, `/book/history`	`400 invalid_market`, `400 invalid_parameter`, `404 book_not_found` (book only)
`GET /v1/books/health`	`400 invalid_parameter`
`GET /v1/insights/strategies/{id}`	`400 invalid_parameter`, `404 strategy_not_found`, `503 graph_unavailable`
`GET /v1/relations/{left_venue}/{left_id}/{right_venue}/{right_id}`	`400 invalid_market`, `400 invalid_parameter`, `404 market_not_found`, `404 relation_not_found`, `503 graph_unavailable`
`GET /v1/stream`	`400 invalid_parameter`, `429 too_many_streams`, `503 stream_unavailable`; after the stream opens, errors arrive as an `error` event
`POST /mcp`	`401` as above; REST errors inside a tool call come back as a tool error whose text is `GET <path> answered <status> <code>: <message>`

Observed examples

curl -s "https://api.routeur.app/v1/events?limit=999" -H "X-API-Key: $ROUTEUR_API_KEY"

{"error":{"code":"invalid_parameter","message":"Invalid or unsupported query parameter: limit."}}

curl -s "https://api.routeur.app/v1/markets/nyse/ABC" -H "X-API-Key: $ROUTEUR_API_KEY"

{"error":{"code":"invalid_market","message":"Use /v1/markets/{kalshi|polymarket}/{market id}."}}

curl -s "https://api.routeur.app/v1/markets/kalshi/NOPE-NOPE" -H "X-API-Key: $ROUTEUR_API_KEY"

{"error":{"code":"market_not_found","message":"The market is not in the latest graph."}}

curl -s "https://api.routeur.app/v1/relations/kalshi/A-B/kalshi/A-B" -H "X-API-Key: $ROUTEUR_API_KEY"

{"error":{"code":"invalid_market","message":"Use /v1/relations/{kalshi|polymarket}/{market id}/{kalshi|polymarket}/{market id} with two different markets."}}

curl -s "https://api.routeur.app/v1/rulebooks/kalshi/thing/KXCPI" -H "X-API-Key: $ROUTEUR_API_KEY"

{"error":{"code":"invalid_rulebook","message":"Use /v1/rulebooks/{kalshi|polymarket}/{series|event|market}/{id}."}}

An MCP tool call for a missing market:

{"jsonrpc":"2.0","id":4,"result":{"content":[{"type":"text","text":"GET /v1/markets/kalshi/NOPE-NOPE answered 404 market_not_found: The market is not in the latest graph."}],"isError":true}}

Handling errors

Branch on error.code, never on the message.
Treat 400 and 404 as bugs in the request or ids that no longer exist; do not retry them unchanged.
On 429, wait Retry-After seconds. On 503 and 500, wait a few seconds and retry once.
504 timeout means the query was too wide for 15 seconds: narrow the window or the limit.
A market or event that returns 404 today can appear after the next hourly graph run, which reads the latest complete crawls.

Get started

Concepts

Agents & MCP

Webhooks

Reference

The error envelope

Every code

By endpoint

Observed examples

Handling errors

The error envelope

Every code

By endpoint

Observed examples

Handling errors

Related