Error Contract Reference

May 27, 2026 · View on GitHub

Error contract reference for user-facing CLI and exported helper behavior.

CLI Error Contract

Exit Codes

0: successful execution
1: usage error, invalid arguments, sync/persistence failure, or command failure

Streams

Human-readable command output is written to stdout.
Argument/usage and failure diagnostics are written to stderr.
On invalid command/arguments, usage text is printed with a non-zero exit code.

Canonical Usage Errors

Examples:

unknown subcommand: Unknown command: <name> plus usage
switch with missing index: Missing index. Usage: codex-multi-auth switch <index>
switch with invalid index: Invalid index: <value>

JSON Mode Contract

The following commands support --json and produce pretty-printed JSON objects:

codex-multi-auth forecast --json
codex-multi-auth report --json
codex-multi-auth fix --json
codex-multi-auth doctor --json
codex-multi-auth verify-flagged --json

Compatibility guarantees:

Output is valid JSON.
command field identifies the command family.
Documented top-level sections remain stable unless a migration note is provided.

HTTP/Error Mapping Contract (Fetch Helpers)

Entitlement Mapping

Upstream entitlement-like 404 payloads are normalized to 403 with entitlement_error payloads.
Entitlement errors are not treated as rate limits.

Rate-Limit Mapping

Upstream usage-limit indicators normalize to rate-limit semantics.
handleErrorResponse may return parsed rateLimit.retryAfterMs metadata.

Response Normalization

Error responses are normalized to JSON error payloads with a stable error.message field.
Diagnostics may include request/correlation IDs when available.

Runtime Rotation Proxy Error Contract

The default-on localhost Responses proxy returns JSON error payloads with a stable error.code field.

Code	HTTP status	Meaning
`runtime_rotation_proxy_not_found`	`404`	Request path or method is outside the supported Responses/model discovery surface
`runtime_rotation_proxy_unauthorized`	`401`	Local request did not include the per-process proxy client key
`runtime_rotation_proxy_payload_too_large`	`413`	Request body exceeded the proxy safety cap
`codex_runtime_rotation_pool_exhausted`	`429` or `503`	No managed account can currently service the runtime request
`codex_pinned_account_unavailable`	`503`	A manual pin is set (via `codex-multi-auth switch`) but the pinned account is rate-limited, cooling down, disabled, or blocked by policy. Run `codex-multi-auth status` for details, or `codex-multi-auth unpin` to allow rotation
`codex_runtime_rotation_proxy_error`	`500`	Proxy failed before forwarding the request

Pool exhaustion includes a reason, retry_after_ms, and a hint to run codex-multi-auth rotation status. Pinned-account-unavailable responses include a pinnedAccountIndex field identifying the pinned account, a structured reason field carrying the runtime skip reason (for example rate-limited, cooling-down:auth-failure, circuit-open, disabled, workspace-disabled, policy-blocked, missing, already-attempted) or null when no reason was recorded, and an account_skip_reasons map keyed by account index that mirrors the pool-exhausted response shape. The human-readable message appends the same reason in parentheses when present (see issue #486).

Options-Object Compatibility Contract

For selected exported helper APIs, options-object forms were added without removing positional signatures.

Supported dual-call forms include:

selectHybridAccount(...) and selectHybridAccount({ ... })
exponentialBackoff(...) and exponentialBackoff({ ... })
getTopCandidates(...) and getTopCandidates({ ... })
createCodexHeaders(...) and createCodexHeaders({ ... })
getRateLimitBackoffWithReason(...) and getRateLimitBackoffWithReason({ ... })
transformRequestBody(...) and transformRequestBody({ ... })