Errors and request IDs
Handle machine-readable errors, throttling, and asynchronous outcomes.
API errors include a readable message and a stable machine-readable code. Handle the code rather than matching the message text.
{
"errors": [
{
"message": "This idempotency key was already used with different request values.",
"code": "idempotency_conflict"
}
],
"requestId": "client-trace-01"
}An error entry may also include field to identify an invalid input.
HTTP status codes
| Status | Meaning | Next step |
|---|---|---|
| 400 | Invalid JSON, values, pagination, or operation | Correct the request using its error code. |
| 401 | Missing, invalid, or expired authentication | Check or replace the credential. |
| 403 | Scope, role, email, MFA, or entitlement restriction | Resolve the named access requirement. |
| 404 | The resource is unavailable to this caller | Check the UUID and workspace. |
| 405 | Unsupported HTTP method | Use the method shown in the reference. |
| 409 | Resource state, uniqueness, or idempotency conflict | Read existing state before submitting another write. |
| 413 | Request is too large | Keep the JSON body at or below 256 KiB. |
| 429 | Request throttled | Honor Retry-After before retrying. |
| 5xx | A server-side failure | Retry reads or supported keyed writes with bounded backoff. |
The API provides a Retry-After header on 429 responses. Do not assume a fixed allowance of requests per minute; use the returned delay.
Correlate a request
All API responses include X-Request-ID. Error bodies repeat it as requestId.
You may supply a trace value using X-Request-ID: 1–64 letters, digits, dots, underscores, or hyphens, beginning with a letter or digit. Invalid values are replaced by a generated identifier. Record the returned value with the timestamp and endpoint when contacting support.
X-Request-ID identifies a request for diagnostics. The legacy write-body field also named requestId is an alias for Idempotency-Key and has different semantics. See idempotency.
Deployment failures
A successful HTTP request can return a deployment whose current state is failed. The transport succeeded; the deployment did not. Check status, review its build or runtime logs, and inspect the returned deployment's safe error details.
A local timeout while polling means your observation window ended. It does not cancel the remote job or prove it failed. Resume with the existing deployment or operation ID.
Safe diagnostics
Store status, error code, request ID, resource IDs, and SDK version where appropriate. Avoid recording complete request bodies, bearer credentials, revealed variables, or unrestricted application logs. SDK exception messages omit sensitive response contents by default; explicitly accessed error entries still require careful handling.