Errors
Interpret RestoreTrust error envelopes, status codes, retries, and project-boundary responses.
Loading documentation…
Powered by heyo
JSON errors use a consistent envelope:
Some errors add a stable code, structured detail, or quota information. Quota
values in this example are illustrative; use the values returned for the current
organization and plan:
| Status | Meaning | Client action |
|---|---|---|
400 | Invalid JSON, field, filter, cursor, or project-scoping pattern | Correct the request; do not retry unchanged. |
401 | Missing, invalid, paused, expired, or under-scoped credential | Replace the credential or grant the required scope. |
403 | Authenticated but not allowed, project mismatch on a scoped request, or plan/quota restriction | Check key binding, permissions, plan, and quota. |
404 | Resource not found or intentionally hidden across a project boundary | Verify the ID and use the API key bound to the owning project. |
409 | Current resource state prevents the operation, such as a referenced resource, running check, or unavailable report PDF | Inspect code; resolve the conflict or wait for PDF generation when pending. |
410 | Deprecated endpoint removed | Follow the replacement named in the error message. |
429 | Request limit or temporary concurrency limit exceeded | Honor Retry-After when present and back off before retrying. |
502 | A requested dependent read or delivery failed | Retry with bounded backoff if the operation is safe. |
503 | A required service or feature is temporarily unavailable | Retry with bounded backoff; honor Retry-After when present. |
504 | A live request timed out | Retry with bounded backoff. |
A resource that belongs to another project is reported as not found. The API does not reveal whether that ID exists outside the caller's project.
Retry 429, 502, 503, and 504 only when the endpoint and operation are safe for your workflow. Use exponential backoff with jitter and a maximum attempt count. Do not automatically retry validation, authentication, permission, or conflict errors.
The request rate limiter returns 429 with Retry-After in whole seconds until the exceeded limit admits another request (at least one second). Temporary concurrency limits can also return 429; honor the header when present and otherwise use bounded backoff. Limit values can vary by deployment, so integrations should not assume a fixed ceiling.
A report PDF returning 409 with code: "report_pdf_pending" is a wait condition: poll the existing report with backoff, then retry its download when ready. report_pdf_failed and report_pdf_unavailable need a different response; repeatedly downloading does not generate a PDF. See Reports.
Log the HTTP method, path template, response status, error code, and your own correlation identifier. Never log the X-API-Key value or credential-bearing request headers.