Unsupported parameter max_tokens: Fixing GPT-5 and GPT-6 Requests
Updated for the OpenAI Chat Completions and Responses APIs, GPT-5 and GPT-6 model families. Tested on the OpenAI Python SDK 1.x and later with Python 3.11 and 3.12.
Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead. is a 400 that shows up the moment an existing integration is pointed at a GPT-5 or GPT-6 model. The code worked against gpt-4o minutes earlier, so the natural conclusion is that the API is broken. It is not. The parameter was deprecated, and the newer model families enforce the deprecation instead of quietly ignoring it.
This tutorial covers why the request is rejected, what the replacement parameter counts, and how to fix it when the offending key is buried inside a framework you do not control.
What the error looks like
The response is an HTTP 400 with an invalid_request_error body. The Python SDK raises it as BadRequestError:
{
"error": {
"type": "invalid_request_error",
"message": "Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead."
}
}
The message names both the rejected key and its replacement, which makes this one of the more helpful errors in the API. The same request against an older model such as gpt-4o or gpt-4.1 succeeds, because those models still accept the legacy field.
Why it happens
The API reference still lists max_tokens, but marks it deprecated and documents the constraint directly: the value is deprecated in favor of max_completion_tokens and is not compatible with reasoning models. Reasoning models generate internal reasoning tokens before any visible output, and those tokens are billed as output. A parameter named max_tokens implied a budget for the text you can read; on a reasoning model the same ceiling also has to cover thinking you never see. The rename makes that explicit, and GPT-5 and GPT-6 models inherit the stricter behavior.
The rejection is deliberate rather than lenient. Silently honoring max_tokens as an output cap would produce responses that stop mid-sentence for reasons the caller cannot explain, so the API fails the request instead. That is why the fix is a rename and not a workaround at the response layer.
Two other situations produce the identical error even when your own code is clean. The first is a library that builds the JSON body for you and always writes max_tokens. ClickHouse hit exactly this in its AI functions: the OpenAI provider writes max_tokens and temperature into every chat-completions body, and the option map rejects unknown keys, so no setting inside SQL could rename the field. The second is an explicit n parameter. The same schema notes that newer models reject an explicit n, even n=1, so a helper that always sends n=1 will fail for the same reason and with a similar message.
Fix 1: send max_completion_tokens
On /chat/completions, rename the field and keep the same value shape. It is a plain integer cap:
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
model="gpt-6.2-sol",
messages=[{"role": "user", "content": "Summarize this changelog in three bullets."}],
max_completion_tokens=800,
)
print(response.choices[0].finish_reason)
print(response.usage)
The rename changes semantics, not just spelling. max_completion_tokens is an upper bound for everything the model generates, including reasoning tokens. A value that produced a comfortable answer on gpt-4o can be consumed entirely by reasoning on a hard prompt, leaving finish_reason at length with an empty or truncated message. Read the reasoning share from the usage object after your first runs and size the cap from what you observe rather than from the old model's numbers.
Fix 2: move the call to the Responses API
New integrations are better served by the Responses API, where the cap is named max_output_tokens and there is no legacy alias to trip over. The parameter has the same meaning: visible output plus reasoning tokens:
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6.2-astra",
reasoning={"effort": "medium"},
input="Write a migration checklist for moving this service to Postgres 17.",
max_output_tokens=4000,
)
print(response.output_text)
One detail that bites during migration: the request schema sets a minimum of 16 for max_output_tokens. Passing a very small value such as 5 is rejected during validation, not clamped, so tiny budgets used for smoke tests need adjusting when you port them.
Fix 3: when a library owns the request body
If the parameter is hardcoded in a dependency and the library gives you no knob, you have three options in order of preference: upgrade the library to a version that knows about the newer models, patch the call site if the body is built in your code, or translate the field between your code and the API. The translation is a few lines if you are sending raw HTTP and can drop the compatibility field before the request leaves:
import os
import httpx
def create_completion(payload: dict) -> dict:
if "max_tokens" in payload:
payload["max_completion_tokens"] = payload.pop("max_tokens")
response = httpx.post(
"https://api.openai.com/v1/chat/completions",
headers={"Authorization": "Bearer " + os.environ["OPENAI_API_KEY"]},
json=payload,
timeout=120,
)
response.raise_for_status()
return response.json()
Use that shim as a temporary measure, not as architecture. It hides a real incompatibility from the rest of the system, and the next strictness change will surface somewhere you cannot intercept. For server-side SQL engines and workflow tools, the durable fix is upstream: report the hardcoded field and pin the model family you can actually configure.
Preventing it
Keep generation settings in one module instead of scattering literals across call sites, then run a single-call smoke test against one model from each family you ship to. A CI job that sends a ten-token prompt to gpt-6.2-sol and asserts a 200 catches this class of error before a deployment does. When you upgrade a model, diff the request body rather than the prompt. If you maintain a wrapper library, keep a per-model parameter allowlist so an unsupported key fails in your own code with your own message, not three layers down in an HTTP 400.