Stable error envelope
HTTP errorJSON
{
"error": {
"type": "invalid_request_error",
"code": "<stable_machine_code>",
"message": "<human-readable explanation>",
"param": "<field_or_null>",
"request_id": "<request_id>"
}
}Branch on error.code, show message to the operator, and include request_id when contacting support. Do not parse prose.
Retry by operation type
Reads
Retry with backoff
Repeat the same GET after transient 429 or 5xx responses. Respect server retry guidance.
Creates
Reuse the key
After a transport failure, resend the byte-equivalent request with the original idempotency key.
Async work
Inspect the ID
Poll the known resource. Do not create a replacement because a watch window ended.
When the copilot appears stalled
- 1
Inspect the existing workflow
Look at its phase, blockers, references, watch cursor, and next actions.
- 2
Complete the named handoff
Credentials and raw files require the UI. Spend and rollout changes require approval.
- 3
Resume the same workflow
Use resume after the external condition changes. Do not ask the copilot to recreate upstream resources.
- 4
Abandon only when the goal changed
Abandon records the terminal reason and prevents accidental continuation.
Common recovery decisions
authentication_errorA human updates the workspace or connector credential.
permission_errorCheck role, mode, workspace, and whether the operation is human-only.
conflict_errorRe-read the resource; your expected state or plan hash is stale.
rate_limit_errorBack off, keep the same resource ID or idempotency key, and retry.
api_errorRetry safe reads; inspect durable writes before resubmitting.