API

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": "..." }
  }
}
  • code is stable. Program against it.
  • message is for people and can change.
  • request_id matches the X-Request-ID response header. Quote it when you contact support.
  • details is 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.