Error messages

Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.

Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.

The whole message, as the API returns it:

Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.

It arrives as an HTTP 400. Someone running GPT-5.5 through Unsloth Studio posted the raw body this month:

{
  "error": {
    "message": "Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.",
    "type": "invalid_request_error",
    "param": "max_tokens",
    "code": "unsupported_parameter"
  }
}

Why the model refuses max_tokens

OpenAI's reasoning models think before they answer, and those hidden reasoning tokens count toward the output. The old max_tokens field was built before that existed. In the official Python library (we read openai-python 3.19.2) its description now says: "This value is now deprecated in favor of max_completion_tokens, and is not compatible with o-series models."

The replacement is defined as "an upper bound for the number of tokens that can be generated for a completion, including visible output tokens and reasoning tokens." The old field is only deprecated for the rest of the catalog, so older chat models still accept it, which is why a config can work for months and then break the day someone picks a newer model from the list.

The fix in your own code

Rename the field. In Chat Completions:

client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello"}],
    max_completion_tokens=4000,
)

The Responses API never took max_tokens at all; its field is max_output_tokens, with the same meaning.

Don't carry the old number over unchanged. A limit of 500 that was plenty for GPT-4o's visible reply can be used up entirely by reasoning, and OpenAI's reasoning guide warns that a cut-off response "might occur before any visible output tokens are produced, meaning you could incur costs for input and reasoning tokens without receiving a visible response." The same guide recommends "reserving at least 25,000 tokens for reasoning and outputs" when you're starting out.

When a tool you didn't write sends it

Most of the 1,030 GitHub issues with this line (our count on September 26, 2026) come from apps and gateways, not from anyone's own script. The usual cause is a generic "OpenAI-compatible" adapter that always writes max_tokens. Cloudflare's AI Gateway provider is a clean example: issue #653 shows its Unified route sending max_tokens through the generic adapter, while the native OpenAI adapter maps the field correctly for the same model.

So in a tool, look for a provider setting that says OpenAI specifically instead of "custom" or "OpenAI-compatible", and check the app's issue tracker for this exact line, since a fix is often already merged. If neither helps, a model from the older chat family will accept the request unchanged while you wait for a fix.

A sibling error often shows up right after this one is fixed: reasoning models also refuse a temperature other than the default, covered on its own page.