## Why
Requests that exceed the server's advertised WebSocket message size limit can fall back to HTTP without first uploading the oversized message.
## What changed
Read `x-codex-websocket-max-message-bytes` from the handshake response and check the serialized request's byte length before sending. Route oversized requests through the existing HTTP fallback. Ignore missing or invalid limits, and remove the close-code-specific wording from the size-limit error.
## Testing
Add a fallback test that advertises a one-byte limit and verifies zero WebSocket generation requests and one HTTP request.
GitOrigin-RevId: 03b42012ca77d6b046e937fef8e6335d855a1c10
## Why
A WebSocket close with code `1009` before any text arrives indicates that the request exceeds the peer's message size limit. Retrying the request over another WebSocket does not address that limit.
## What changed
- Classify these early size rejections as requiring HTTP fallback and switch transports without exhausting WebSocket retries, including during prewarming.
- Preserve ordinary stream retry behavior for size closes after any text frame and for other close codes.
## Testing
Add integration coverage for early size rejections during generation and prewarming, size closes after metadata, rate limits, or response creation, and ordinary closes.
GitOrigin-RevId: 4550d289bb414fec1faae2a195bcc635d394117b
## Why
An explicit denial from a workspace inference hook should stop the request, including retries and compaction model fallback.
## What changed
Recognize `inference_hook_denied` provider errors and preserve the provider's message, with a fallback when none is supplied. Expose the distinct `inferenceHookDenied` error through the app-server protocol and generated schemas and SDK types. Treat the denial as non-retryable during turns, compaction, and guardian review.
## Testing
Add coverage for terminal denials over HTTP, SSE, and WebSocket, error serialization and persistence in `thread/read`, and compaction failures that preserve token usage and history without retrying or falling back to another model.
GitOrigin-RevId: 2ebd480f01e52f4e6bd3db8a0f92d5814d18ccb1
## Why
HTTP 400 responses with `context_length_exceeded` need to reach context-window recovery so manual compaction can retry with less history. Streaming context-window failures should end the stream immediately.
## What changed
- Map `context_length_exceeded` through the shared terminal provider error parser for HTTP 400 responses and events without an HTTP status.
- Return SSE context-window failures immediately.
- Preserve retryable handling for WebSocket errors carrying HTTP 503, even when their code is `context_length_exceeded`.
## Testing
Add coverage for WebSocket status handling and immediate SSE termination with retry headers. Update the manual compaction test to verify recovery from an HTTP 400 context-window error by dropping one history item and retrying.
GitOrigin-RevId: 56d8c831c2fad2ca1318318a3b4258fcc516d689
## Why
An `invalid_access_program` or `unsupported_access_program` streaming error should end the stream immediately, even if a later `response.completed` event arrives or the error includes a retry header.
## What changed
Map both error codes to `ApiError::InvalidRequest` and stop processing the response stream on invalid requests. Preserve a nonblank provider message, falling back to an explanation that the requested access program cannot be used with the model.
## Testing
Extend the terminal-error test to cover both codes in `error` and `response.failed` events, verifying that retry headers are ignored and the stream ends before a later completion event.
GitOrigin-RevId: 5431a2babec64eae5cdf6c138b98e91e84778e79
## What changed
Recognize `content_policy_violation` in HTTP 400 responses and streamed errors as a dedicated, non-retryable error. Preserve the provider's message and available HTTP status, use a fallback message when needed, and report `CodexErrorInfo::InvalidPrompt` to clients.
End the response stream immediately on this error and stop compaction from falling back to the current model after a content policy rejection. Add redacted diagnostic output and a dedicated sampler failure reason.
## Testing
Extend coverage for HTTP and wrapped WebSocket errors, missing or blank provider messages, terminal stream failures with retry headers, and content policy rejections during local and remote compaction on model downshift.
GitOrigin-RevId: 592170ac30c07b0b303a8d5cb15bd35c8f821b55
## What changed
Recognize `access_program_not_enabled` in HTTP 403 responses and response stream errors as a dedicated, non-retryable error. Preserve HTTP diagnostic details and provider stream messages, with a default message when none is supplied.
Stop SSE streams immediately on this error and avoid triggering WebSocket fallback for explicit access program denials. Add a fixed diagnostic label for doctor output and telemetry.
## Testing
Extend coverage for HTTP and WebSocket denials, immediate SSE termination despite retry headers, and doctor diagnostic redaction.
GitOrigin-RevId: 3a41f7bb80ad5e13a87e831b458d17cdd19a4b62
## Why
Uploaded audio was rejected even for audio-capable models. Invalid or expired recordings also need to be excluded from later requests so users can continue the conversation.
## What changed
- Accept uploaded audio when the selected model supports audio; otherwise, preserve valid sibling input and report the unsupported attachment before inference.
- Track successful audio decoding by model and provider, and attribute provider rejections against the exact submitted request. Preserve attachments when attribution is ambiguous.
- Persist confirmed rejected file IDs across compaction and resume, omitting them from future requests without rewriting retained user history.
- Check audio availability before remote compaction and retry once without an unambiguously rejected recording. Include guidance to remove or replace affected attachments in audio errors.
## Testing
Add unit and scenario coverage for uploaded audio across follow-up turns, compaction, cold and paginated resume, model switching, ambiguous rejections, expired files, and queued or interrupted input.
GitOrigin-RevId: e701901e7b1c0865c9f2a5918197215f549b06c0
## What changed
Map provider `budget_reached` errors to `SessionBudgetExceeded` for HTTP 400 responses and streaming failures. End SSE streams immediately on this error, ignoring retry headers and later completion events, and display `budget reached` in the TUI.
## Testing
Add coverage for HTTP error classification, immediate SSE termination without retries, WebSocket error delivery and subsequent request recovery, and TUI error rendering and task-state cleanup.
GitOrigin-RevId: 6a62d699cdb9cb446214cacfacd0c9ed68bf21a6
## What changed
Map audio size, data, format, and sample-rate validation failures to `InvalidAudioInput` for HTTP 400 responses and streamed errors. Preserve the provider's message, falling back to `Invalid audio input.` when it is absent or blank.
Classify these errors as non-retryable and expose them as `BadRequest`. Redact their messages in doctor diagnostics and group them as invalid requests in telemetry.
## Testing
Add coverage for all six audio validation codes across HTTP errors, streamed `error` events, and `response.failed` events, checking error classification, message preservation, and the absence of retries. Extend doctor diagnostic redaction coverage for `InvalidAudioInput`.
GitOrigin-RevId: 0a59964bcabd83997bdb32fc9318a5482dac33b0
## What changed
- Recognize `policy_capacity_unavailable` in HTTP and streaming API errors and expose it as `policyCapacityUnavailable` through the app-server protocol and generated bindings.
- Display “Policy-restricted capacity is unavailable. Please try again later.” while preserving overload retry behavior based on `Retry-After`.
- Handle the new error in TUI overload rendering, reviewer retries, and error telemetry.
## Testing
Add coverage for HTTP and streaming error classification, retry advice, WebSocket terminal error attribution, protocol serialization, and TUI rendering with and without an upstream message.
GitOrigin-RevId: 1b9536fba1e11cc891dcf689aee35410d82f5412
## Why
Provider errors with code `model_not_found` should end the turn immediately and preserve the provider's message instead of triggering retries.
## What changed
- Recognize `model_not_found` in HTTP 400, 403, and 404 responses and in streamed `error` and `response.failed` events.
- Preserve the provider message and any available HTTP status, and expose `modelNotFound` through the app-server protocol and generated schemas and SDK types.
## Testing
Add coverage for HTTP classification, statusless stream errors, and terminal failures without retries across HTTP, SSE, and WebSocket responses. Verify that `thread/read` preserves the error reported by the live notification.
GitOrigin-RevId: 88f824ac03c8c9669915b1e40c67b76c08326fbe
## Why
Synchronous auth header construction could silently return no credentials when managed authentication became unavailable. Callers need an error to avoid sending requests with missing or partial authentication.
## What changed
- Make `AuthProvider::add_auth_headers`, `to_auth_headers`, and auth header telemetry fallible, and propagate failures through request and WebSocket setup.
- Return a transient error when managed authentication is unavailable, and preserve network policy denials through auth error conversion.
- Retry transient MCP authentication errors while treating build errors and policy denials as terminal.
- Cancel local MCP event streams before resolving authentication so cleanup still works when credentials become unavailable.
## Testing
Add regression coverage for rejected partial authentication, async header resolution, terminal auth errors without sending requests, managed account changes, MCP retry classification, and local stream cancellation after authentication becomes unavailable.
GitOrigin-RevId: 39d981e232cba1e302de502a2fa6239101114ed1
## Why
Terminal `response.incomplete` errors discard reported token usage. Counting that usage as a new context baseline can also double-count input and trigger unnecessary compaction on the next turn.
## What changed
- Carry the response ID and valid reported usage with incomplete-response errors.
- Record usage for sampling and foreground compaction in cumulative totals, rollout records, budgets, and token-usage contributors without replacing the context baseline. Preserve the original terminal error, including when accounting exhausts the budget or cancellation races the error.
- Charge incomplete background compaction requests to the rollout budget without publishing foreground token usage.
- Ignore missing or malformed usage rather than estimating it.
## Testing
Extend coverage for SSE and WebSocket incomplete responses, rollout usage records, compaction accounting, deferred token-count events, and token-usage contributors. Add regressions for unnecessary compaction on the next turn and background compaction publishing foreground usage.
GitOrigin-RevId: bf1ee6df3912052ab7c19e1c6af8ad3dc4b07675
## Why
Incomplete responses such as `max_output_tokens` were classified as stream errors, allowing retries and compaction model fallback after the response had hit its output limit.
## What changed
Introduce `ResponseIncomplete` errors that preserve the server-provided reason and stop stream processing immediately. Make these errors non-retryable and stop compaction without falling back to the selected model. Record incomplete responses separately in sampler failure metrics.
## Testing
Add regression tests that verify incomplete responses surface a terminal error without retries over SSE and WebSocket, and that compaction stops without retrying or switching models for both local and remote compaction.
GitOrigin-RevId: 6e107d441b9bf03fa47ea47b88eeb94b71a9f729
## Why
Responses stopped by `content_filter` previously followed generic stream-error retry handling without guidance about the block. Retried requests need instructions to explain the limitation and offer a permitted alternative.
## What changed
- Recognize content-filter failures as a distinct error while preserving retryability and the existing public error representation.
- Append developer guidance to the conversation after each sampling block, retaining delivered output and using the existing retry handling.
- Support a model catalog override through `model_messages.content_filter_guidance`. Missing, null, blank, or values exceeding 512 UTF-8 bytes fall back to bundled guidance.
- The bundled guidance tells the model to avoid reproducing or working around blocked content, briefly explain the limitation, offer a permitted alternative, and continue unrelated authorized work.
## Testing
Add a scenario and request-history snapshot covering repeated blocks, catalog guidance on each retry, retained partial output, and eventual completion. Add error-mapping assertions for retryability, public error classification, and error text.
GitOrigin-RevId: ba0c201b3a5a3acf5cfa971332027240e0690225
## What changed
- Recognize `flex_unavailable` in HTTP 429 responses and streamed `error` and `response.failed` events. End normal turns without retries and report `Flex capacity unavailable.`
- Expose `flexUnavailable` through the core and app-server protocols and generated schemas and SDK types.
- Keep Flex capacity failures eligible for Guardian review and sampler retries, with a distinct telemetry classification.
- Map unexpected HTTP responses to `HttpConnectionFailed`, preserving their status codes.
## Testing
Add regression coverage for terminal Flex failures over HTTP, SSE, and WebSocket, HTTP 504 status preservation after a stream retry, and protocol serialization. Update Guardian retry and sampler recovery tests to cover Flex failures.
GitOrigin-RevId: f2e03a6d2d36a6d9748c35952e40397f8670d121
## Why
HTTP retries used local backoff even when the server supplied `Retry-After`. Relative retry delays also failed to account for time spent propagating errors or reporting retries.
## What changed
- Parse `Retry-After` delay seconds and HTTP dates into a monotonic deadline captured when response headers arrive.
- Honor that deadline for HTTP retries, falling back to local backoff when valid advice is absent.
- Preserve deadlines through API and Bedrock error mapping, stream retries, and exhausted retry state. Expired advice remains a zero delay instead of triggering local backoff.
## Testing
Add coverage for header parsing, deadline countdown and expiry, error mapping after exhausted HTTP retries, and delayed stream retry notifications. Update Responses and remote compaction tests to verify that HTTP retries honor `Retry-After`.
GitOrigin-RevId: a2eff02946e5524f29e06f7ba1431e3d339261a4
## Why
`invalid_prompt` responses were classified as generic invalid requests, losing the server's specific error classification.
## What changed
Add `InvalidPrompt` variants to the API and core error types and serialize the core protocol classification as `invalid_prompt`. Recognize the code in HTTP 400 responses, wrapped WebSocket errors, and SSE `response.failed` events while preserving server messages and keeping the error non-retryable. Map it to `other` in the app-server v2 protocol.
## Testing
Extend coverage for typed error mapping, missing and blank messages, protocol conversion, and guardian retry handling. Exercise HTTP and SSE failures in core integration tests, asserting the error message, serialized classification, and a single request without retry.
GitOrigin-RevId: 5d9a299a013b06158a4dc27a4054f3dbc5fd0f4d
## Why
Streaming `bio_policy` failures were classified as generic invalid requests, losing their policy-specific classification.
## What changed
- Add `BioPolicy` errors across the API and core protocol, recognizing streaming failures and HTTP 400 responses, including wrapped WebSocket errors.
- Preserve server messages and use a biological-risk fallback when the message is missing or blank.
- Treat bio policy errors as non-retryable in core and guardian handling, and classify them in diagnostics and telemetry.
- Map `BioPolicy` to `other` in the app-server v2 protocol.
## Testing
Add coverage for error classification, message preservation and fallbacks, HTTP and wrapped WebSocket responses, guardian retry decisions, and app-server conversion. Extend the core integration test to verify that bio policy failures emit a typed error and complete the turn after a single request.
GitOrigin-RevId: 78c2647e8fc8f80297cb8a23fff06ab141099632
## Why
App-server clients need the explanation and steering instruction returned with a
misalignment policy violation to offer a user-confirmed continuation. Missing or
incomplete details must continue to behave as a terminal block.
## What changed
- Parse optional misalignment classification, explanation, and steering details
from streamed and HTTP Responses errors and propagate them through core errors.
- Include the details in live app-server `error` and `turn/completed` payloads and
export the corresponding protocol schemas and TypeScript types.
- Keep explanations and steering messages out of serialized rollout events and
redact them from debug output.
- Document how clients can resume with `turn/start` after user confirmation.
## Testing
- Cover streamed, HTTP, and WebSocket-wrapped errors, including malformed and
classification-only details.
- Verify live app-server notifications expose resumable details without writing
the explanation or steering message to the rollout.
GitOrigin-RevId: 329258a444c2cd91d0c57ab1720830b33ddcfac5
## What changed
- Classify `response.failed` events with the `rate_limit_exceeded` code as a distinct retryable error while preserving any parsed retry delay.
- Expose the error as `rateLimitExceeded` through the core protocol and app-server schemas after stream retries are exhausted.
- Preserve the upstream message for TUI display while keeping it out of telemetry summaries.
## Testing
- Cover SSE classification, retry metadata, protocol conversion and serialization, exhausted stream retries, telemetry redaction, and TUI rendering.
GitOrigin-RevId: 02dab4d3477dcd7653a58c49c4bd38687a616579
## What changed
- Recognize `misalignment_policy_violation` errors from response streams and HTTP 400 or 403 responses.
- Preserve the upstream message, use a fallback for blank messages, and treat the error as non-retryable.
- Expose `misalignmentPolicyViolation` through the app-server protocol and generated schemas so turns fail with a typed terminal error.
## Testing
- Cover streamed and HTTP policy violations, fallback messages, retry behavior, and app-server turn completion.
GitOrigin-RevId: fd3485bf0be7bfe3d51c078bbc36a081692fd57f
# External (non-OpenAI) Pull Request Requirements
Before opening this Pull Request, please read the dedicated
"Contributing" markdown file or your PR may be closed:
https://github.com/openai/codex/blob/main/docs/contributing.md
If your PR conforms to our contribution guidelines, replace this text
with a detailed and high quality description of your changes.
Include a link to a bug report or enhancement request.
**Goal**: Prevent response.failed events with `invalid_prompt` from
being treated as retryable errors so the UI shows the actual error
message instead of continually retrying.
**Before**: Codex would continue to retry despite the prompt being
marked as disallowed
**After**: Codex will stop retrying once prompt is marked disallowed
Charlie Marsh