Errors

Errors come back as an RFC 7807 problem object: a type, a title, a status, a detail and a timestamp, usually with a suggestions array that proposes a rewrite. Some types add machine-readable fields of their own — query-unservable carries a reason, for instance.

The type slug is the stable surface. Branch on it, and never on the prose in detail, which is written for a human and changes.

Read the body, not the Content-Type header. The body is problem+json-shaped and the response is sent as application/json, so a client that branches on the content type will not recognise its own errors.

An unbound variable:

{
  "type": "https://whisper.security/errors/query-error",
  "title": "Query Error",
  "status": 400,
  "detail": "Variable 'nosuchvar' is not defined in this scope. Bind it with MATCH (nosuchvar:LABEL …), WITH … AS nosuchvar, UNWIND … AS nosuchvar, or YIELD nosuchvar.",
  "timestamp": "2026-08-09T19:12:47.704324212Z",
  "suggestions": [
    {
      "kind": "undefined_variable",
      "rationale": "The query references 'nosuchvar', which was never bound by a preceding MATCH / WITH / UNWIND / YIELD in scope.",
      "rewrite": "Introduce every RETURN/WHERE variable with a preceding MATCH (var:LABEL ...) / WITH var / UNWIND ... AS var / YIELD var.",
      "confidence": "high",
      "safeToAutoRetry": false
    }
  ]
}

Each suggestions entry carries a kind, a rationale, a rewrite, a confidence, and safeToAutoRetry — the field an automated client should read before re-running anything on your behalf. suggestions is sometimes present and empty; treat that the same as absent.

Every row below was reproduced against production on 2026-08-09.

This set is measured, not exhaustive. The engine defines more type slugs than the six reproduced above; internal-error and schema-drift are two that could not be forced from a client and so are not documented here with a body shape. Read the type you get, not a list.

The API is read-only. Write clauses (CREATE, MERGE, SET, DELETE) are rejected as a query-error before anything runs, with a readonly_engine suggestion; nothing you send can modify the graph.

The invalid-key gotcha

An unknown or malformed API key does not fail the request. The query API never returns 401 — an unrecognised key is treated as though you had sent no key at all, so the symptom is never an auth error. It is a query that ran yesterday and comes back refused today, or a result thinner than the one you expect. When results look wrong, re-check the header format on the Cypher API page.

The MCP connector behaves the other way round. There an unrecognised bearer is rejected outright: HTTP 401 {"error":"Invalid API key"}. Same key, two surfaces, two behaviours — so a working MCP session proves nothing about the header your HTTP client is sending, and the reverse.

explain() and whisper.history() read from a live threat-intelligence backend at call time. If that backend is briefly unreachable, the procedure returns available: false with a retryAfter value instead of a score; the HTTP request itself still succeeds. Respect the retry interval and call again. Note that batching indicators with UNWIND ... CALL explain(...) makes one backend call per item, so runtime grows with the list; keep unwound lists short.

Two response headers exist to make a request findable after the fact: X-Request-Id identifies the request, and X-Served-By names the replica that answered it. Both were present on every response, signed in and signed out. Quote them when you report a problem — without the request id nobody can find your request in the logs.

When opening a support ticket, include:

1. The full request URL and request body
2. The full response, headers and body
3. The x-request-id header from the response
4. The time the request was made (UTC)

Start at Support, or email support@whisper.security.