Error Codes & Rate Limits

HTTP status codes, RFC 7807 problem-detail format, rate limits, and the anonymous-tier fallback gotcha.

Updated May 2026

WhisperGraph error responses follow RFC 7807 problem-detail format. Every error response is a JSON object with at least type, title, status, and detail.

{
  "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
}

HTTP status codes

Code	Condition	What to do
`400`	Invalid Cypher syntax	Check your query for typos or unsupported syntax. See the Cypher Syntax reference.
`400`	Query depth exceeds plan limit	Reduce traversal hops or upgrade your plan. Anonymous requests are capped at 2 hops; higher tiers allow deeper traversals — see the pricing page.
`401`	The request was rejected for an authentication reason	Check your `X-API-Key` header. Note that an unknown or malformed key normally degrades to anonymous access rather than returning 401 — if results look thin, see the anonymous-access note in the API reference.
`408`	Query timeout	Add `LIMIT`, narrow the pattern, or anchor with `{name: "..."}`. The default and maximum per-request timeouts are plan-specific — check them with `CALL whisper.quota()` (`defaultTimeoutMs` / `maxTimeoutMs`).
`429`	Hourly or daily quota exceeded, or too many concurrent queries	Wait for the reset time in the response headers, or upgrade your plan.
`500`	Server error	Retry once. If it persists, contact support with the request ID.
`502`	Upstream service error	A downstream graph backend returned an error. Usually transient — retry with exponential backoff.
`503`	External service unavailable	An infrastructure data source (BGP, WHOIS, threat-intel) is temporarily unreachable. Affected fields may return null, and procedures like `explain()` may return `available: false` with a `retryAfter` value.
`504`	Gateway timeout	The request timed out at the gateway. Same as 408: anchor the query better, add `LIMIT`, simplify the traversal.

Rate limits

Quota is enforced on an hourly and a daily window. When you hit a 429, the response includes the rate-limit headers:

X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset — your hourly quota, queries left this hour, and when the hourly window resets.
X-DailyLimit-Limit / X-DailyLimit-Remaining / X-DailyLimit-Reset — the matching values for the daily window.

Authenticated responses include these headers on every request, not just 429s — so you can watch your remaining quota without a separate call. Wait until the relevant reset time and retry, or run CALL whisper.quota() to see your current usage. For per-plan limits and quotas see the pricing page.

Reporting issues

When opening a support ticket, include:

The full request URL and request body
The full response (headers + body)
The request_id from the response (if present)
The time the request was made (UTC)

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

PreviousFeed Categories NextGlossary

Error Codes & Rate Limits