Errors

Read type to decide what to do, code to know why, param to know where, and message to know what to change. Only 503 and 500 are ever 5xx; nothing is billed on an error, with the two exceptions on Retries and billing outcomes.

• invalid_json: The body is not JSON, or not an object. Retry: No.
• missing_required_parameter: A required field is absent; param names it. Retry: No.
• invalid_type: A field has the wrong JSON type. Retry: No.
• invalid_value: A value is out of range or malformed. Retry: No.
• unknown_parameter: A field the gateway does not know, at any depth; param names it. Retry: No.
• unsupported_parameter: A known OpenAI field HIPS does not accept, or a feature the named model does not advertise. Retry: No.
• unsupported_value: n other than 1, stream_options without stream, a message role or part type not accepted. Retry: No.
• stateful_not_supported: store, metadata, previous_response_id, conversation. Retry: No.
• context_length_exceeded: The prompt is over the model's context_length; the prompt is never truncated. Retry: No.
• max_tokens_exceeded: max_tokens over the model's max_output_tokens. Retry: No.
• invalid_image: An image part or input cannot be decoded, is of an unsupported type or over the pixel limit. Retry: No.
• request_too_large, input_too_large, too_many_inputs, upload_too_large: A limit of the Limits page. Retry: No.
• task_mismatch: task is not the model's task. Retry: No.
• not_a_language_model: A task model or a task-model deployment named on an OpenAI-compatible route. Retry: No.
• deployment_stopped: The dep_ is in stopped; start it in the Console. Retry: No.
• upload_not_found, upload_expired, upload_incomplete, upload_mismatch, upload_consumed: An upload_id that is unknown or another workspace's, past expires_at, without bytes, with bytes that differ from the declaration, or already consumed. Retry: No (upload_incomplete: after the PUT).
• invalid_requirement: A requirement header or field with an unknown value. Retry: No.
• requirement_conflict: Two requirements that cannot both hold, a header and a hips field that differ, a pool the model is never offered in, personal with an always-on deployment. Retry: No.
• stable_price_not_in_force: pricing_mode: stable with no stable price covering this workspace, model and period. Retry: No.
• use_jobs: A synchronous task the gateway can tell will exceed the synchronous limit. Retry: As a job.
• invalid_idempotency_key, idempotency_key_reused, idempotency_in_progress: The idempotency rules. Retry: The last one, later.
• request_timeout: The body stopped arriving. Retry: Yes.

• missing_api_key: No Authorization header, or not a bearer. Retry: No.
• invalid_api_key: Unknown, malformed or revoked key. The message never says which. Retry: No.
• insufficient_credit: The balance does not cover the request's maximum cost at the bound quote. On the free plan with the allowance used, the message names when it resets. Retry: After a top-up.
• key_scope_denied: The key's kind excludes the route. Retry: No.
• model_not_on_plan: The model or feature is not in the workspace's plan. Retry: No.
• region_not_on_plan: A region requirement on a plan without region selection. Retry: No.
• pool_not_allowed: A pool the workspace may not use for this model. Retry: No.
• workspace_unverified: The workspace's owner has not passed identity verification; the message names the Console's verification screen. Retry: After verification.
• workspace_paused: The workspace is paused: by balance, by an administrator, by a dispute, by a budget hard stop or by an owner. The message says which and where to resolve it. Retry: After resolution.
• plan_lapsed: The subscription lapsed and no owner has yet acknowledged the free plan's request-data policy or paid; the policies hold meanwhile. Retry: After acknowledgment or payment.
• workspace_deleted: The workspace is deleted (restorable 30 days). Retry: After restore.

• model_not_found: Unknown catalog id, alias, pinned id or dep_; another workspace's dep_. Retry: No.
• job_not_found, upload_not_found: An id in the path that is unknown or another workspace's. Retry: No.
• result_expired: A job's result read after expires_at. Retry: No.
• route_not_found: Unknown path. Retry: No.
• route_not_available: A route of this contract not yet served (/v1/responses before validation). Retry: No.
• method_not_allowed: A known path with another method; Allow is sent. Retry: No.

• rate_limit_exceeded: A rate limit; param is requests, tokens, units or uploads; Retry-After. Retry: Yes, after Retry-After.
• concurrency_limit_exceeded: Too many concurrent streams or active jobs; param is streams or jobs; Retry-After. Retry: Yes, after Retry-After.

• no_capacity: No eligible worker under the request's requirements, in any pool the requirements allow; Retry-After. Retry: Yes.
• pool_unavailable: The named pool has no eligible supply for this model now and fallback is off; the other pool may have; Retry-After. Retry: Yes, or with fallback.
• deployment_not_ready: The dep_ is allocating or loading, or waits for its version's tariff (tariff_pending); Retry-After. Retry: Yes.
• overloaded: Eligible workers exist and every one is saturated, or the queue is full; Retry-After. Retry: Yes.
• internal_error: A fault in HIPS. Nothing billed. Retry: Once.
• attempt_failed: Every attempt failed for a reason that is not the client's and retries are exhausted. Nothing billed. Retry: Once.

One data: line holding the error envelope, then the stream closes without [DONE]. OpenAI clients raise on it. The usage record shows the outcome. See Streaming.