Errors

Every error response uses a consistent JSON envelope so you can handle failures uniformly.

Envelope shape

{
  "error": {
    "code": "not_found",
    "message": "Program not found",
    "requestId": "7c0c1e9b-9c2b-4f7e-9c91-7b9c8e2c1a93"
  }
}

code: a stable, machine-readable error code (see below).
message: human-readable detail. May change; don't branch on it.
requestId: echoes your X-Request-Id header if you sent one, otherwise a server-generated UUID. Include it when contacting support.

Code	Typical status	Meaning
`invalid_request`	`400`, `405`	Malformed body, parameters, or method.
`unauthorized`	`401`	Missing, invalid, revoked, or expired API key.
`forbidden`	`403`	The key's scope doesn't allow this action (e.g. a write with a `read_only` key).
`not_found`	`404`	Resource missing, or not owned by your team.
`conflict`	`409`	`Idempotency-Key` collision, or the resource isn't in a state that allows the operation.
`rate_limited`	`429`	Request quota exceeded.
`internal_error`	`422`, `500`, `503`	The Engine failed to compute a result (`422`), an unexpected server error (`500`), or the Engine is unreachable (`503`).

Status	Meaning
`400`	Invalid request: malformed input, parameters, or a missing `Idempotency-Key` on a write.
`401`	Missing, invalid, revoked, or expired bearer token.
`403`	The API key lacks the required scope.
`404`	Resource not found (or not owned by your team).
`409`	`Idempotency-Key` reused with a different body, or the resource isn't ready (e.g. creating a program before the part finishes processing).
`422`	Well-formed but unprocessable; the Engine reported an error for this resource.
`429`	Rate limit exceeded.
`500`	Unexpected server error.
`503`	The Engine is unavailable. The write was rolled back; retry later.

Branch on the error.code, not the human-readable message; messages may change.
Treat 429 and 5xx responses as retryable with backoff.
A 409 from creating a program usually means the part isn't ready yet. Poll the part, then retry; a new Idempotency-Key is not needed if the body is unchanged.
Other 4xx responses indicate a problem with the request itself. Fix it before retrying.

See the API Reference for the per-endpoint list of error responses. Each documented status shows the specific code it returns.