Errors
A refused request answers with an HTTP status and a JSON body that names the reason in a stable, machine-readable code.
The error body
Most endpoints answer with this body:
{
"error": {
"code": "lease_expired",
"message": "the lease has ended",
"request_id": "8f3c2a71-...",
"details": { "lease_id": "..." }
}
}
codeis stable. Program against it.messageis for people and can change.request_idmatches theX-Request-IDresponse header. Quote it when you contact support.detailsis present only when the endpoint has more to say.
Some older endpoints put code at the top level instead, with error as the message: {"error": "...", "code": "not_found"}. To handle both, read error.code, and fall back to code.
Each endpoint in the API reference lists the error codes its handler returns. A service behind the handler can return others, so treat the list as a guide, not a contract.
Status codes
| Status | Meaning | What to do |
|---|---|---|
| 400 | The request is malformed: bad JSON, a missing or invalid field (invalid_json, invalid_request, validation_error). |
Fix the request. Do not retry it unchanged. |
| 401 | No valid credential (unauthorized, unauthenticated). |
Check the key or refresh the token. See Authentication. |
| 402 | The account cannot take on new spend (payment_required, quota_exceeded on some endpoints). |
Settle billing or raise the limit. Reads keep working. |
| 403 | You are signed in but may not do this (forbidden, permission_denied, person_required, elevation_required). |
Ask an administrator for the permission, or do it from your own session in the console. |
| 404 | It does not exist, or you may not see it (not_found). The API does not say which. |
Check the ID and the organization. |
| 409 | It conflicts with the current state (conflict, build_in_progress, managed_by_build_lease). |
Read the current state, then decide. |
| 410 | It is gone for good (workspace_deleted). |
Do not retry. |
| 415 | The body is not JSON (content_type). |
Send Content-Type: application/json. |
| 422 | It is valid but cannot be done now (failed_precondition). |
Read the message. |
| 429 | Too many requests or a quota is used up (rate_limited, quota_exceeded). |
Wait for Retry-After. See Limits and retries. |
| 5xx | Something on our side, or a dependency, is unavailable (unavailable, service_unavailable, *_unavailable). |
Retry with backoff. |
Fail closed
When the server cannot decide a request, for example because it cannot read a policy, check a permission or write the audit entry, it refuses with 503 rather than letting it through. Codes such as policy_unavailable, authorization_unavailable and audit_unavailable mean exactly that. Retry later.