DocsAPIErrors

Errors

Errors from the query endpoints come back in the same envelope as answers. This page lists the codes, where they appear, and what to do about each.

01Error envelope

The query endpoints report errors in the response envelope, with status: "error", answer: null and one or more { "code", "message" } objects in errors. On /api/query it is the response body; on /api/query/stream it is the data of the final event.

JSON

{
  "request_id": "3f1c9a2e-7b4d-4e8a-9c61-2d5f0b8e4a17",
  "status": "error",
  "answer": null,
  "sources": [],
  "usage": {},
  "errors": [
    { "code": "invalid_api_key", "message": "API key is invalid." }
  ]
}

Switch on code; show message to people. A failed run can carry several errors, and sources and usage may be filled in if the run got far enough.

Two kinds of response use a different shape:

A request body that fails validation gets HTTP 422 with { "detail": [ … ] }, one entry per problem.
The /api/console/* endpoints answer errors with { "detail": "…" }. A write refused as cross-site gets 403 with { "detail": { "code": "CROSS_SITE_REQUEST", "error": "Cross-site request refused" } }.

02HTTP status codes

For the query endpoints:

Code	Meaning	What to do
200	The run ended. `status` says whether it completed.	Check `status`. See Failed runs.
401	No key, or a key that does not exist.	Fix the key. Don't retry as is.
403	The key has been revoked.	Use an active key.
422	The body failed validation.	Fix the request. Don't retry as is.
429	No research runs left this month.	Wait for the next month or move to a larger plan. Retrying does not help.
503	The key could not be checked just then.	Retry after a short wait.

On /api/query/stream, the 401, 403 and 503 cases arrive as an HTTP 200 stream holding an error event and a final event; 429 keeps its status and carries the same two events. See Streaming.

For the /api/console/* endpoints: 400 for a blank key name, 401 without a valid session, 403 for a cross-site write, and 404 for a key or run that is not yours or does not exist.

03Error codes

Code	HTTP	Meaning
missing_api_key	401	No key in `Authorization: Bearer` or `X-Api-Key`.
invalid_api_key	401	The key is not one ResearchAnything issued, or does not start with `ra-`.
key_inactive	403	The key has been revoked.
identity_db_unavailable	503	The key could not be checked because the account database did not answer.
quota_exceeded	429	This month's research runs are used up. The error also carries `limit`, `used`, `plan` and `period` (`"month"`).
session_store_unavailable	200	The run could not be started.
engine_crash	200	The run stopped on an unexpected failure.
engine_error	200	Part of the run failed, for example the analysis of the question or the writing of the answer. `message` says which.
stream_pump_failed	—	Stream only: sending events failed part-way. A `final` event follows.

JSON — quota_exceeded

{
  "request_id": "9d8c7b6a-5f4e-4d3c-2b1a-0f9e8d7c6b5a",
  "status": "error",
  "answer": null,
  "sources": [],
  "usage": { "latency_ms": 0, "tokens_in": 11, "tokens_out": 0 },
  "errors": [
    {
      "code": "quota_exceeded",
      "message": "Monthly research run limit reached for this plan.",
      "limit": 3,
      "used": 3,
      "plan": "free",
      "period": "month"
    }
  ]
}

04Retry guidance

Every accepted call starts a new run and uses a research run from your monthly allowance, whether or not it completes. There is no way to resume a run or replay one by id. So retrying costs allowance, and it pays to retry little.

When to retry

503 identity_db_unavailable: retry after a few seconds. No run was started.
A dropped connection: the run has been counted either way. If a call to /api/query drops, the server carries on and the finished run's answer appears in the Console's run timeline. Closing a stream stops its run. Retry once if your code still needs the answer.

Failed runs

A 200 with status: "error" means the run started and did not complete; its research run has been used. Retry at most once. If it fails again, read the messages in errors before trying further.

When not to retry

401, 403, 422: the request or the key is wrong. It will fail the same way until you fix it.
429 quota_exceeded: the allowance is used up until the next calendar month. Stop sending calls; each refusal is still recorded in your usage.