Errors

Fail with the fix. Every Rekall error carries a type, a human message, and the exact command or code that resolves it.

Fail with the fix

Every Rekall error includes what happened, why, and the exact command or code to fix it. This is a design principle, not a nicety — the fix field is always present.

Error envelope

{
  "error": {
    "type": "store_not_found",
    "message": "No store named 'contracts'.",
    "fix": "Create it: POST /v1/stores {\"name\": \"contracts\"} — or `rekall stores create contracts`."
  }
}

Prop

Type

The SDKs map each type to a typed exception subclass that carries the fix string, so you can catch precisely and surface the remedy. See the TypeScript and Python error sections.

The eight error types

HTTP	`type`	When	Fix carried
`400`	`invalid_request`	Malformed body or out-of-range parameter	The valid range / corrected shape
`401`	`unauthorized`	Missing or invalid API key	How to pass or create a key
`404`	`store_not_found`	No store by that name or id	The create command
`409`	`store_already_exists`	Creating a store whose name is taken	Use it by name, or pick another
`404`	`document_not_found`	No document by that id in the store	List, or ingest it
`413`	`document_too_large`	A document or batch exceeds size limits	Split the batch / use `ingestStream`
`429`	`rate_limited`	Project request-rate exceeded	Retry after `Retry-After`; SDKs auto-retry
`500`	`internal`	Unexpected server error	Retry; contact support if it persists

Examples

`400 invalid_request`

{ "error": {
  "type": "invalid_request",
  "message": "`max_hops` must be between 1 and 8, got 12.",
  "fix": "Set max_hops to a value in [1, 8]. The engine stops as soon as it finds the answer, so 6 (the default) is right for most corpora."
}}

`401 unauthorized`

{ "error": {
  "type": "unauthorized",
  "message": "No API key provided.",
  "fix": "Pass `Authorization: Bearer <key>`. Create a key in the dashboard, or with `rekall keys create` on an enterprise deployment."
}}

`404 store_not_found`

{ "error": {
  "type": "store_not_found",
  "message": "No store named 'contracts'.",
  "fix": "Create it: POST /v1/stores {\"name\": \"contracts\"} — or `rekall stores create contracts`."
}}

`409 store_already_exists`

{ "error": {
  "type": "store_already_exists",
  "message": "A store named 'contracts' already exists.",
  "fix": "Use it directly — stores are addressable by name: POST /v1/stores/contracts/search — or pick a new name."
}}

`404 document_not_found`

{ "error": {
  "type": "document_not_found",
  "message": "No document 'supplier_a' in store 'contracts'.",
  "fix": "List documents with GET /v1/stores/contracts/documents — or ingest it: POST /v1/stores/contracts/documents."
}}

`413 document_too_large`

{ "error": {
  "type": "document_too_large",
  "message": "Document 'handbook' is 41.2 MB; the per-request limit is 32 MB.",
  "fix": "Split the batch: send this document in its own request, or use the SDK's ingestStream which batches automatically."
}}

`429 rate_limited`

Carries a Retry-After header (seconds).

{ "error": {
  "type": "rate_limited",
  "message": "Rate limit exceeded: 100 requests/s per project.",
  "fix": "Retry after the interval in the Retry-After header. SDK clients retry automatically with jittered backoff."
}}

`500 internal`

{ "error": {
  "type": "internal",
  "message": "An unexpected error occurred.",
  "fix": "Retry the request. If it persists, contact support@rekall.sh with the request id."
}}

SDK behavior

The SDK clients retry idempotent operations (and 429s) automatically with jittered backoff. All other errors raise a typed exception whose .fix you can log or show the user verbatim.

On this page