Get started
Errors
Distinguish invalid inputs, denied access, conflicts, rate limits and uncertain outcomes.
Customer API error envelope
Inspect HTTP status first, then error.code. Messages explain a failure but are not stable machine conditions. Preserve error.request_id with the correlation response headers. Console endpoints can use a different error projection; inspect their reference pages.
{
"error": {
"code": "VALIDATION_ERROR",
"message": "A safe description",
"request_id": "<request-id>"
}
}Common outcomes
| HTTP | Meaning | Action |
|---|---|---|
| 400 | Invalid request | Correct input; do not retry unchanged. |
| 401 | Invalid authentication | Check scheme and credential scope. |
| 403 | Denied permission or policy | Resolve access with your administrator. |
| 404 | Absent or out-of-scope resource | Check the ID and institution. |
| 409 | Version, approval or idempotency conflict | Read the original resource before another write. |
| 429 | Rate limit reached | Honor Retry-After and back off. |
| 503 | Unavailable or unresolved outcome | Query the original operation and preserve its identifiers. |
Do not turn uncertainty into a duplicate
A timeout or unavailable dependency does not establish that the original operation had no effect. Query its stable ID and retain its original request and idempotency key. A new key can request a second instruction.