Operate
Errors and remediation
Map stable error codes to corrective action and retry only explicitly transient failures.
Error contract
Every error response includes a stable code, HTTP status, retryable flag, message, and correlation ID. Build application behavior from the code and retryable flag rather than matching message text.
Non-retryable errors
Input, authentication, entitlement, authorization, missing-resource, conflict, and expired-artifact errors need a corrected request or user action.
- invalid_request: validate the payload against the operation schema
- unauthorized: replace the missing, revoked, or malformed key
- quota_exhausted: upgrade or add API capacity
- idempotency_conflict: use the original body or a new logical-action key
- artifact_expired: publish again to create a new artifact
Transient errors
Retry rate_limited and service_unavailable only when retryable is true. Honor Retry-After and use exponential backoff with full jitter.