Operate

Errors and retries

Handle authentication, scope, validation, idempotency and transient failures without unsafe retries.

Error envelope

JSON

{
  "error": {
    "code": "INSUFFICIENT_SCOPE"
  }
}

OAuth protocol errors use the standard top-level error and error_description fields. Action and management routes use the structured envelope above.

HTTP handling

Status	Meaning	Client behavior
202	Approval or asynchronous completion required	Persist action ID; follow handoff and poll.
400	Invalid input, forbidden request shape, or beta idempotency-reuse response	Correct the request; do not retry unchanged.
401	Missing, expired or revoked token	Reauthorize through the supported flow.
403	Scope or Fullness policy denial	Do not retry; request only justified authority.
404	Action not found in this grant/workspace	Verify identifier and tenant context.
409	Contracted idempotency conflict response	Do not change intent under the same key.
429	Throttled	Use bounded backoff and response metadata.
5xx	Transient service failure	Retry reads; retry writes only with the original key and intent.

During the controlled beta, handle both HTTP 400 with IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST and HTTP 409 as terminal idempotency conflicts. This preserves compatibility while the runtime is aligned to its OpenAPI 409 response.

Correlation and evidence

Retain the response correlation ID, action ID and activity URL in operational logs. Do not log access tokens, authorization codes, PKCE verifiers, webhook secrets or financial payloads unnecessarily.