Errors & Rate Limits

Errors come back as application/problem+json with a type, title, status, and detail, and often a suggestions array that proposes a rewrite. Some error types add machine-readable fields of their own. A depth-exceeded error looks like this:

{
  "type": "https://whisper.security/errors/query-depth-exceeded",
  "title": "Query Depth Exceeded",
  "status": 400,
  "detail": "Query depth 3 exceeds maximum allowed depth of 2. Reduce traversal hops or upgrade your plan for deeper queries.",
  "actualDepth": 3,
  "maxAllowedDepth": 2
}

The API is read-only. Write clauses (CREATE, MERGE, SET, DELETE) are rejected with a 400 parse error; nothing you send can modify the graph.

The invalid-key gotcha

An unknown or malformed API key does not normally fail the request. It degrades gracefully to the anonymous tier, so the symptom is not a 401: it is a query-depth-exceeded error on a 3-hop query that worked yesterday, or thinner rate limits than you expect. When results look wrong, run CALL whisper.quota() and check the isAnonymous value — if it is true while you are sending a key, the key is not being read. Header formats are on the Cypher API page.

Quota is enforced on an hourly and a daily window. A 429 carries a Retry-After header; wait it out and retry. Authenticated responses also include running counters on every response, not just on 429s, so you can watch your remaining quota without a separate call:

• X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset — the hourly window.
• X-DailyLimit-Limit / X-DailyLimit-Remaining / X-DailyLimit-Reset — the daily window.

From inside Cypher, whisper.quota() returns your plan tier, usage, and caps:

CALL whisper.quota() YIELD key, value RETURN key, value

[
  {"key": "plan", "value": "FREE"},
  {"key": "isAnonymous", "value": false},
  {"key": "hourlyLimit", "value": "500"},
  {"key": "hourlyUsed", "value": 12},
  {"key": "hourlyRemaining", "value": "488"},
  {"key": "dailyLimit", "value": "5000"},
  {"key": "maxQueryDepth", "value": "3"},
  {"key": "maxResponseLimit", "value": "5000"}
]

Metadata calls are free: whisper.quota() itself and the db.* introspection procedures (db.labels(), db.relationshipTypes(), db.propertyKeys(), db.schema()) do not count against your quota.

Tier caps

A query with more hops than your tier allows returns HTTP 400 with a query-depth-exceeded error before it runs. When a chain exceeds your tier, split it into anchored single hops joined with WITH, or reach for a procedure: explain() collapses a deep threat traversal into one call.

Queries are time-capped. A query that runs too long returns 408 with a query-timeout error. The request body accepts a timeout field in milliseconds, clamped to your plan maximum and a global ceiling (see the API Reference).

If you hit the cap, the fix is almost always the same: anchor the query on an indexed name, add a LIMIT, bound intermediates with WITH ... LIMIT, or replace the scan with a procedure. One special case never finishes at any tier: a global edge count like MATCH ()-[r]->() RETURN count(r). Use GET /api/query/stats instead — the totals there are precomputed and instant. The full set of habits is in Best Practices.

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.

When opening a support ticket, include:

1. The full request URL and request body
2. The full response, headers and body
3. The request_id from the response, if present
4. The time the request was made (UTC)

Open a ticket at console.whisper.security/support or email support@whisper.security.