Operate
Errors & retries
Diagnose conflicts and recover from ambiguous requests.
On this page
Read the error and operation IDs
Failures return an error object with a stable code, message and request ID. Record the HTTP status, code, request ID and X-Operation-Id when present. Avoid logging API keys, webhook secrets or sensitive task content. Each operation’s API details render its error schema from the contract.
Decide whether to retry
| Response | Check | Recovery |
|---|---|---|
| 400 | Input, template fields, path or payload | Correct the request before retrying |
| 401 | Platform key or trigger-specific authentication | Fix the credential or signature |
| 402 | Wallet credit or Project budget admission | Fund credit or adjust the budget |
| 404 | Key scope, resource ID and parent IDs | Use the correct scope and hierarchy |
| 409 | Idempotency conflict, active work or lifecycle state | Reconcile the resource and wait for transient conflicts |
| 413 | Transport body size | Reduce the upload or event batch |
| 429 | Trigger admission rate | Retry with backoff and the same event identity |
| 503 | Provider, audit backend or runtime availability | Check current capability and retry after recovery |
Exact operation responses and service codes are documented in the API documentation. Different operations can use the same HTTP status for different reasons.
Recover from a lost response
A timeout or missing audit result does not establish that an operation failed. For Run submission, steering and fork operations, keep the same idempotency key and exact body. Inspect the affected resource and audit operation facts before changing the key.
Create operations without idempotency support need reconciliation before retrying. For example, a webhook may already exist after its creation response was lost. List definitions; if the one-time secret was not saved, rotate it rather than assuming another read will reveal it.
Handle workspace conflicts
File and Skill operations use the Environment lifecycle lock. Queued or running work, initial checkpoint capture, terminal checkpoint capture, rollback and pause/resume transitions can all prevent access. Read the reason-specific code and current Environment/Run state.
A ready checkpoint can appear before the worker’s memory pause finishes and releases the lock. Retry transient transitions with bounded backoff. Persistent checkpoint failure needs investigation; it is not a reason to bypass the lock or rerun completed model work.
Recover an event observer
Keep the Run ID and reconnect the event stream using your last processed event ID. Poll Run status independently. Do not submit the same task under a new key because an SSE connection ended. See events, webhook recovery and audit.