Parameters and error codes.
The complete Chat Completions parameter table and every error code the API returns. The quickstart and guides are on the main documentation page.
Chat Completions parameters
| Parameter | Type | Behavior |
|---|---|---|
model | string | Required. The exact ID of a model listed by /v1/models. |
messages | array | Required. Up to 2,000 turns with role system, developer, user, assistant or tool. Content is a string or an array of text parts (joined with a newline). Assistant history may also contain refusal parts and tool_calls. |
max_tokens / max_completion_tokens | integer | Maximum output tokens, including reasoning. Send one, never both. Default: the smaller of 8,192 and the model's max_output_tokens. |
stream / stream_options | boolean / object | Server-sent events. stream_options (only with stream: true): include_usage adds a final usage chunk; include_obfuscation is accepted and ignored. |
temperature / top_p | number | 0–2 and 0–1. Forwarded to the selected supplier. |
stop | string or array | One string or up to four strings, 200 characters each. |
seed | integer | Best effort. Forwarded where the supplier honours it; never a cross-route determinism guarantee. |
presence_penalty / frequency_penalty | number | −2 to 2. Routes whose supplier would ignore them are skipped; if none remains the request fails with 400 before any charge. |
tools / tool_choice | array / string or object | Up to 128 function tools. function.parameters is optional (defaults to an empty object schema). tool_choice: none, auto, required or a named function. |
parallel_tool_calls | boolean | Forwarded only with function tools. The default true is not sent to suppliers that do not need it. |
response_format | object | json_object or json_schema where the model lists the format in structured_formats. json_schema needs name; description, schema (default: any JSON object) and strict are optional. {"type": "text"} is accepted and dropped. |
reasoning_effort | string | none, minimal, low, medium, high, xhigh or max. minimal uses low and xhigh uses max (as on the Responses API). The mapped level must be in the model's reasoning_efforts. |
n | integer | Only 1. |
user / logprobs: false | string / boolean | Accepted for SDK compatibility; never forwarded or stored. |
Null means omitted. Many SDKs send null for options you did not set. An explicit null on any OpenAI chat parameter, on optional message fields (name, tool_calls, refusal, function_call, audio) and on optional tool or json_schema fields is treated as if the field were absent and is never forwarded. An unknown field is rejected even when its value is null.
Rejected with 400 invalid_parameter: logprobs: true, top_logprobs, logit_bias, top_k, min_p, repetition_penalty, reasoning (object), include_reasoning, thinking, metadata, store, service_tier, prediction, modalities, audio, web_search_options, functions / function_call (legacy), verbosity, prompt_cache_key, safety_identifier, provider routing overrides, any other unknown field. The error’s param and message name the field; submitted values are never echoed.
Instructions are folded. Many open-weight chat templates accept only one system message, at the start, and no developer role. The gateway therefore merges every system and developer message, in order, into one leading system message (separated by a blank line) before dispatch; a single leading system message is sent unchanged. Instructions placed later in a conversation therefore apply to the whole conversation.
Model fields
Returned for each model by GET /v1/models and GET /v1/models/{model}.
| Model field | Meaning |
|---|---|
id / name / object / created / owned_by | The exact model ID to send, a display name, "model", when the current catalog version was published (Unix seconds) and "zerodayapi". |
context_length / max_output_tokens | Context window and the largest accepted output limit, in tokens. The default output cap is the smaller of 8,192 and max_output_tokens. |
capabilities | streaming, tools, structured, reasoning and vision flags. Image, audio and file input is currently refused on every model. |
reasoning_efforts | reasoning_effort values a reviewed route supports (chat minimal/xhigh map to low/max). Empty means none can be requested. |
structured_formats | response_format types a reviewed route supports: json_object and/or json_schema. |
default_reasoning_effort | The effort applied when you send none; absent when the supplier default is used. |
pricing | unit (micro_usd_per_million_tokens), input, output, cache (cached input reads) and, where the model bills them, cacheWrite (prompt-cache writes) as decimal strings. |
retention | require_zdr (only routes reviewed for zero retention) or allow_provider_retention. |
routing_contract | mode (exact, base_model or refusal_removed), base_model where applicable, and the disclosure that applies to backup routes. |
Error codes
Every error body carries code, param (the offending field, when there is one) and request_id.
| Status | Code | Meaning |
|---|---|---|
400 | invalid_json | The body is not valid JSON. Check quoting and whitespace; the body is never echoed back. |
400 | invalid_parameter | Unknown field, wrong type or out-of-range value, malformed message or tool. param and the message name the field. |
400 | unsupported_parameter | Responses/Messages only: a feature that needs stored state or server-side tools (previous_response_id, conversation, background, prompt, item_reference, forced hosted tools, server tools, mcp_servers, container, a non-JSON-schema output format). |
400 | unsupported_capability | The model lacks a requested capability: tools, structured output, reasoning, streaming, an uncertified reasoning effort or format, image/audio/file content, or a sampling parameter no route honours. |
400 | conflicting_limits | Both max_tokens and max_completion_tokens were sent. |
400 | output_limit | The output limit is above the model's max_output_tokens. |
400 | context_length_exceeded | Prompt plus output limit exceed the context window (OpenAI's code; Messages uses Anthropic's "prompt is too long" wording). Earlier releases returned context_limit. |
400 | too_many_messages | More than 2,000 conversation turns. |
400 | invalid_idempotency_key | Idempotency-Key is longer than 128 characters. |
400 | upstream_validation | The selected supplier rejected the request before generating. Not retried on other routes and not charged. |
401 | invalid_api_key | Missing, malformed, revoked or expired key. |
402 | insufficient_credit | Available credit is below this request's maximum reservation. |
402 | spending_limit | The account's daily or monthly spending limit would be exceeded. Adjust it in Billing. |
402 | key_daily_limit | This key's daily limit would be exceeded. Raise it on the API keys page or wait until 00:00 UTC. |
402 | key_spending_limit | The key's overall spending cap would be exceeded. |
403 | key_permission / account_disabled | The key lacks models:read or chat:write, or the account is disabled. |
404 | model_not_found / endpoint_not_found | Unknown or unpermitted model ID, or an unsupported path. |
404 | response_not_stored | GET, DELETE or POST /v1/responses/{id}: responses are never stored. |
409 | idempotency_conflict / request_already_admitted | An Idempotency-Key was reused for a different body, or the same request was already admitted. Inspect the original request; nothing is replayed. |
413 | body_limit | The body exceeds 8 MiB (1 MiB on non-inference endpoints). |
415 | content_type | Content-Type is not application/json. |
429 | rate_limit / concurrency_limit | Per-minute request or reserved-token limit, or simultaneous-request limit. Respect Retry-After. |
429 | ip_rate_limit | Too many requests from one IP address. Retry after 60 seconds. |
499 | request_cancelled | Your client closed the connection; recorded in request history. Your client does not receive it. |
502 | empty_completion / invalid_upstream_stream / upstream_contract / upstream_incomplete / ambiguous_upstream_failure | Every compatible route failed its output contract before anything reached you. Empty answers are never charged. |
503 | gateway_busy / capacity_exhausted / no_eligible_route | Temporary gateway load, every compatible route busy, or no route supports this request. Respect Retry-After. |
503 | upstream_service_error / upstream_model_unavailable / upstream_connect / upstream_region_restricted / upstream_rate_limit | Suppliers could not serve the request on any compatible route. |
503 | accounting_unavailable | Attempt finalization is pending. Keep the request ID and inspect it before retrying. |
504 | first_token_timeout / total_request_timeout / upstream_timeout | No first token in time on any route, or the model's total deadline passed. |