Error Codes & Rate Limits

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

Updated May 2026

Error Codes & Rate Limits Documentation

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

CodeConditionWhat to do
400Invalid Cypher syntaxCheck your query for typos or unsupported syntax. See the Cypher Syntax reference.
400Query depth exceeds plan limitReduce traversal hops or upgrade your plan. Plan limits: Anonymous 2 hops, Free 3, Professional 5.
401Invalid API keyVerify your API key. If results look thin, see the anonymous-access note in the API reference.
408Query timeoutAdd LIMIT, narrow the pattern, or anchor with {name: "..."}. Server-side timeout is 30s by default.
429Rate limit exceededWait for the next minute window or upgrade your plan. The X-RateLimit-Reset header tells you when.
500Server errorRetry. If persistent, contact support with the request ID.
502Upstream service errorA downstream graph backend returned an error. Usually transient — retry with exponential backoff.
503External service unavailableAn infrastructure data source (BGP, WHOIS, threat-intel) is temporarily unreachable. Affected fields may return null.
504Gateway timeoutThe query exceeded the gateway timeout (60s). Simplify or split into multiple queries.

Rate limits

When you hit a 429, the response includes:

  • X-RateLimit-Limit — your per-minute quota
  • X-RateLimit-Remaining — queries left in this window
  • X-RateLimit-Reset — unix timestamp when the window resets

Wait until X-RateLimit-Reset and retry. For per-plan limits and quotas see the pricing page.

Reporting issues

When opening a support ticket, include:

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

Email: support@whisper.security

PreviousFeed CategoriesNextGlossary