API Errors
Understand the full failure flow, not just the error name
This page explains how error handling works at runtime: the response envelope, helpful headers, retry posture, and how this differs from the narrower Error Types taxonomy page.
`/docs/api/errors` is the operational playbook; `/docs/api/error-types` is the taxonomy reference.
Use this page when you are implementing runtime behavior or debugging real failures. Use Error Types when you want the stable naming model behind those failures.
What this page covers
API Errors is about handling a failed call end-to-end in production.
Envelope Handling
Read the normalized JSON body and classify what kind of failure happened.
- Inspect `type` first, then `error`, then optional details.
- Keep raw envelopes available for logs and support tools.
- Treat the body as runtime input, not just UI copy.
Header Semantics
Rate-limit and version headers help the runtime decide what to do next.
- Use `Retry-After` for backoff-aware retries.
- Track `X-RateLimit-*` for observability and pacing.
- Use `X-API-Version` in debugging and support workflows.
Debug Flow
Move from failure capture to classification, then to a safe next action.
- Separate setup failures from request-shape failures.
- Keep retry logic inside the runtime adapter.
- Escalate unknown failures with enough metadata to inspect them later.
Read the envelope and the headers together
A good runtime does not look only at the JSON body. The status code, rate-limit headers, and retry metadata often matter just as much as the typed error field.
- Use status plus `type` to classify the branch cleanly.
- Respect `Retry-After` and rate-limit headers for pacing decisions.
- Log request identity and headers without leaking secrets.
Keep operational handling separate from taxonomy design
Error Types tells you how failures are named. API Errors tells you how a running system should respond when one actually happens in production.
- Use this page to design runtime behavior and incident response.
- Use Error Types to define stable branch keys in code and SDKs.
- Link both pages in internal docs so builders know when to use each.
Errors vs. Error Types
These two docs should support different jobs instead of duplicating each other.
| Surface | Primary question answered | When to use it |
|---|---|---|
| API Errors | How should the runtime respond to a failed request right now? | During implementation, debugging, retries, and operator playbooks. |
| Error Types | What stable categories and names does the contract use for failures? | When designing typed branching, SDKs, and contract tests. |
| OpenAPI x-error-codes | Which codes can appear on this specific operation? | When generating clients, fixtures, or endpoint-level expectations. |
Decision Matrix
Use this flow when a live request fails and the runtime needs to decide the next move.
Situation
The response includes `Retry-After` or rate-limit headers
Action
Back off in the runtime and schedule a bounded retry.
Why
The server is explicitly telling you when another attempt is safer.
Situation
The request fails with a validation or missing-field type
Action
Stop and repair the request payload or route choice first.
Why
Transport-level retries will not fix a malformed request.
Situation
The runtime sees an unknown failure pattern
Action
Capture the raw envelope, headers, request id, and escalate for inspection.
Why
Unknown failures should become observable contract or implementation work, not silent loops.
Representative failure payloads
These examples show what the runtime should inspect when a request fails.
{ "error": "Rate limit exceeded", "type": "rate_limit.exceeded"}{ "error": "Missing required field: targetRole", "type": "career_prediction.missing_target_role"}Next surfaces
After the operational flow is clear, go deeper into stable categories and endpoint-specific code lists.