Skip to main content
The API returns structured JSON for every error. Look at both the HTTP status and the code field — the status tells you the category, the code tells you exactly what happened.

​
Envelope

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "docs_url": "https://docs.sitevisit.app/errors/invalid_api_key",
    "request_id": "req_2026060512abc"
  }
}
FieldNotes
codeStable, snake_case identifier. Don’t parse message — use code for branching logic.
messageHuman-readable explanation. May change over time.
docs_urlPermalink to the docs page for this specific code.
request_idEchoes the X-Request-Id response header. Include this when contacting support.
Every response — success or error — sets X-Request-Id. Capture it in your client logs so we can trace failures end-to-end.

​
Status codes

StatusMeaning
200Success.
400Your request is malformed — bad parameter shape, unknown enum value, etc.
401Authentication failed: missing, invalid, or revoked API key.
403Authenticated but not permitted to access this resource.
404The resource doesn’t exist, or it belongs to a different account.
429Rate limit exceeded. Retry with backoff.
500Something broke on our side. We get paged; you should retry with backoff.

​
Common error codes

CodeHTTPMeaningWhat to do
missing_api_key401No Authorization header.Send Authorization: Bearer sv_live_….
invalid_api_key401Key doesn’t match a live, non-revoked key.Check for typos; verify in Settings → Developers.
invalid_parameter400A query parameter was the wrong shape or out of range.Read message — it names the offending field.
invalid_status400status filter wasn’t one of the allowed values.See the API reference for valid enum values per resource.
invalid_priority400priority filter wasn’t LOW, MEDIUM, or HIGH.Use uppercase.
not_found404Resource doesn’t exist or isn’t owned by your account.We never reveal whether a resource exists for someone else.
rate_limited429Too many requests in a short window.Back off — see Retry-After header.
internal_error500Unexpected server failure.Retry with exponential backoff. Include request_id when reporting.

​
Retrying

429 and 5xx responses are safe to retry. We recommend exponential backoff starting at 1 second, capped at 30 seconds, with jitter. 4xx errors other than 429 are deterministic — retrying without changing the request won’t help.