Failure handling

First identify whether the request failed before inference, during routing, or at the provider. The HTTP status and safe error code are more useful than a generic UI exception. Retain the request ID and time; remove bearer headers and private input before sharing diagnostics.

Response example

{"error":{"type":"invalid_request_error","code":"model_not_found","message":"Unknown or disabled model."}}

Request checklist

Confirm the API host, selected path, enabled model ID and token family. A Partner token does not authorize inference. File input must use the selected protocol's field shape; for Responses PDF, file_data includes data:application/pdf;base64, before the encoded bytes.

Response details follow the selected compatibility envelope. Some provider details are replaced with a safe message. Contact Support with your request ID and the error code; do not include credentials or confidential company inputs.

A failed browser fetch means the page did not obtain an accessible response; it does not establish a particular HTTP status or whether the provider was charged. Avoid blind retries and preserve already-received model output when only grading failed.

Investigating partial organization streams

An HTTP success header can be followed by an SSE error. Check the final stream outcome and the project request history, not just the initial status. A generic error may omit provider details. Missing usage must not be treated as zero or guessed from bytes. Inspect partial output and ask Support to help with uncertain outcomes before creating new paid work.

When a failed stream has no provider counters, usage is marked unknown for review and no automatic wire-byte estimate is charged. Observed provider counters are retained. Do not schedule an automatic paid replay just to obtain a cleaner error or usage record.

Dedicated Images failures

For a company image operation, an ambiguous supplier outcome must not turn into an automatic new paid intention. Inspect the saved status even after HTTP 200/202. Keep the original key and actor context for history and read-only lookup; do not switch employees or keys to bypass a conflict. outcome_unknown and review_required need the operator, while retrieval_failed supports only result download retry. Current operation semantics override generic retry advice for these endpoints.

Provider error details and session validation

Provider error bodies are not guaranteed to be passed through unchanged. The decision to expose a provider message is based on its normalized error text, independently of the model, upstream and HTTP status. Unreviewed messages remain hidden behind a safe error response; redaction and the protocol-specific response format still apply. HTTP status and error fields remain useful diagnostics, but they do not select a different disclosure rule for the same normalized text.

An invalid session identifier produces a validation error; correct the field rather than retrying it. An existing recognized session in metadata.user_id is accepted according to the priority of session_id, X-Session-ID, recognized metadata session, prompt_cache_key, then opening content. Different supplied values do not cause a session mismatch error. A plain user identifier is preserved without becoming a conversation ID. A route using this occupied field cannot also insert a managed session; no external sticky binding is promised in that case. Invalid metadata types or duplicate object keys may still produce a validation error on a metadata-session route. Other metadata is preserved. A session identifier is not proof that a timed-out paid request was not accepted. Keep X-Request-ID and inspect the existing request before considering a repeat.

An operator-enabled independent session-header connection can preserve an occupied user identifier while carrying the conversation separately. An absent receiver acknowledgement is an operational diagnostic, not permission to replay a paid request and not a new client-side mismatch error.