OpenAI, Claude and Gemini API "max_tokens is not supported": the right token limit for each

3 hours ago

9 min read

OpenAI, Claude and Gemini logos over a city skyline with the title on the max_tokens is not supported error and the right token limit for each API. Data Studios original cover

Last verified: November 10, 2026

A request that worked for months can suddenly come back with a 400 error saying that max_tokens is not supported with this model and that you should use max_completion_tokens instead. In nearly every reported case the model behind the request changed while the code stayed the same. OpenAI's newer reasoning models refuse the old parameter name on the Chat Completions endpoint, and the error shows up the moment an app, a library or an Azure deployment starts pointing at one of them. The fix is to rename the field to max_completion_tokens on Chat Completions, or to max_output_tokens on the Responses API, and to give it more room than before, because hidden reasoning now counts toward the same limit.

The same confusion spreads to other providers once teams switch models. Claude's own API still uses max_tokens and expects it on every request, while Gemini calls its limit maxOutputTokens in the generateContent API and max_output_tokens in the newer Interactions API. Developers who move code between the three, or who use the OpenAI SDK against Claude or Gemini, hit errors or cut-off answers simply because each endpoint names and counts the limit differently. The reports run from early 2025, when OpenAI's first reasoning models arrived, to March 2026, when an Azure customer saw a fifth of requests fail after a silent model upgrade.

··········

THE OPENAI "MAX_TOKENS IS NOT SUPPORTED" ERROR TEXT AND WHERE IT APPEARS.

The full message comes back from OpenAI's Chat Completions endpoint, and from Azure OpenAI deployments that use the same API, with HTTP status 400. The body names the parameter and gives a machine-readable code that client code can test for:

{'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'}}

That exact text appears in public reports on Microsoft Learn Q&A, the Cursor forum, the OpenAI developer forum and the GitHub issues of command-line tools and AI libraries. In most of them a framework, an SDK wrapper or a plugin added max_tokens by default, and the error surfaced only when the user picked a newer model. A smaller group of early-2025 Azure reports shows the reverse message, "Unrecognized request argument supplied: max_completion_tokens", returned when GPT-4 deployments received the new name.

··········

WHY OPENAI REASONING MODELS REPLACED MAX_TOKENS WITH MAX_COMPLETION_TOKENS.

OpenAI's API reference describes max_tokens as "now deprecated in favor of max_completion_tokens" and states that it "is not compatible with o-series models". The replacement is defined as an upper bound for the tokens generated for a completion, "including visible output tokens and reasoning tokens". The rename exists because reasoning models produce a hidden chain of thought before the answer. Those tokens never appear in the response text, yet they are billed as output and they consume the same budget. A field called max_tokens suggested a cap on the visible answer only, so OpenAI gave the new behavior a new name and made reasoning models reject the old one.

OpenAI's reasoning guide lists the GPT-6 and GPT-5.6 families as reasoning models, with gpt-6-astra as the recommended starting point and gpt-5.6-terra and gpt-5.6-luna as lower-cost options. Microsoft's Azure documentation says the same in plainer words: reasoning models such as the GPT-5 series "use max_completion_tokens instead of max_tokens", and they also refuse temperature, top_p and the penalty parameters. On the Responses API the limit has a third name, max_output_tokens, and it carries the same definition, so a reasoning model spends part of it before writing anything you can see.

··········

TOKEN-LIMIT PARAMETER NAMES FOR OPENAI, CLAUDE AND GEMINI.

Field names are case-sensitive, so maxOutputTokens and max_output_tokens belong to different Gemini interfaces.

........

Provider and endpoint	Token-limit field	Reasoning or thinking counted	Signal when the limit is hit
OpenAI Chat Completions, reasoning models	max_completion_tokens	Yes	finish_reason "length"
OpenAI Chat Completions, max_tokens	Deprecated, rejected by reasoning models	Not applicable	400 unsupported_parameter
OpenAI Responses API	max_output_tokens	Yes	status "incomplete", reason max_output_tokens
Azure OpenAI v1 Chat Completions	max_completion_tokens for reasoning models	Yes	finish_reason "length"
Claude Messages API	max_tokens	Yes, when thinking is on	stop_reason "max_tokens"
Claude OpenAI SDK compatibility	max_tokens or max_completion_tokens	Yes, when thinking is on	Not detailed on the compatibility page
Gemini generateContent (legacy)	generationConfig.maxOutputTokens	Yes	finishReason MAX_TOKENS
Gemini Interactions API	generation_config.max_output_tokens	Yes	Truncated or empty output
Gemini OpenAI compatibility	max_tokens, mapping not documented	Reported yes	Not documented

........

Two rows deserve a caveat. Google's OpenAI compatibility page documents the base URL and the reasoning_effort mapping but says nothing about max_tokens or max_completion_tokens, so the Gemini line rests on a forum answer rather than on documentation. The Claude compatibility layer accepts both names, and Anthropic says that layer "is not considered a long-term or production-ready solution for most use cases".

··········

CAUSES OF THE MAX_TOKENS ERROR AND HOW TO FIX EACH ONE.

Every cause below comes from OpenAI or Microsoft documentation, an accepted moderator answer, or a pattern repeated across independent reports, as marked in the fix column.

........

Cause	How to check	Fix
Your code sends max_tokens to an OpenAI reasoning model	Log the request body; the error names param max_tokens	Rename the field to max_completion_tokens (documented)
A library or plugin adds max_tokens by default	Your code has no max_tokens, yet the payload on the wire does	Update the library, or set its own token option and leave the default unset (several reports)
An Azure deployment was upgraded to a newer model	Response field model shows a newer version than the deployment name	Switch to max_completion_tokens and check the deployment's upgrade policy (accepted moderator answer)
You moved from Chat Completions to the Responses API	The request goes to the responses endpoint	Use max_output_tokens, the only token-limit field there (documented)
Both max_tokens and max_completion_tokens are set	Search the payload for both keys	Send one field only (moderator advice)
The limit is now too low and answers come back empty	finish_reason length or status incomplete with little or no text	Raise the limit or lower reasoning effort (documented)

........

The Azure case is the hardest to spot because nothing changes on the client side. In the March 2026 thread on Microsoft Learn Q&A, about 20 percent of requests to a deployment named for gpt-4o failed from one night onward, and a test request came back from gpt-5.1. The developer confirmed that "the model was auto-updated to 5.1", and the moderator explained that during such a transition some requests reach the newer runtime while others still reach the older one, which produces the intermittent failures.

··········

STEP-BY-STEP FIX FOR THE OPENAI API AND AZURE OPENAI.

1. Find where the request is built. In your own code, search for max_tokens; in a framework or plugin, turn on request logging or a debug proxy and read the JSON that actually leaves your machine.

2. On Chat Completions, replace max_tokens with max_completion_tokens and keep the value as a starting point. Do not send both fields.

3. On the Responses API, use max_output_tokens. The Responses reference lists no max_tokens or max_completion_tokens field.

4. If a third-party tool adds the field, update it first. Some tools handle the new name in newer versions or plugins, as the maintainer of the llm command-line tool did with its separate OpenAI plugin; where a tool still sends max_tokens with no switch to turn it off, the remaining option is a model that accepts the old name, or a different tool.

5. On Azure OpenAI, open the deployment in Microsoft Foundry, check the model version and the upgrade policy, and confirm that the client uses the v1 endpoint ending in /openai/v1/, as Microsoft's samples do.

6. Raise the value. A limit sized for a visible answer of 500 tokens leaves nothing for reasoning, and the request can end before any text appears.

7. Handle the stop signal in code: finish_reason equal to "length" on Chat Completions, or status "incomplete" with reason max_output_tokens on Responses, then retry with a higher limit or a lower reasoning effort.

OpenAI's reasoning guide shows the Responses version of this check. The example is copied from the guide:

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "medium"},
    input=[{"role": "user", "content": prompt}],
    max_output_tokens=300,
)

if (
    response.status == "incomplete"
    and response.incomplete_details.reason == "max_output_tokens"
):
    print("Ran out of tokens")

The Chat Completions equivalent differs only in the field name. The snippet below is illustrative and follows the parameter names in OpenAI's API reference:

completion = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[{"role": "user", "content": prompt}],
    max_completion_tokens=4000,
)
print(completion.choices[0].finish_reason)

··········

[[ADPLUS_300x250_1]]

CLAUDE API: MAX_TOKENS STAYS, AND THINKING COUNTS TOWARD IT.

Anthropic never renamed the field. The Messages API reference lists max_tokens as "the maximum number of tokens to generate before stopping", adds that models may stop before reaching it, and notes that each model has its own maximum, listed on the models overview page. Other request fields carry an "optional" label in the reference and max_tokens does not, and every official example sends it, so a Claude request should always include it. The body has no max_completion_tokens or max_output_tokens field.

Thinking changes how far the number goes. With manual extended thinking, budget_tokens must be at least 1,024 and lower than max_tokens, so that Claude has room to answer after reasoning, and thinking tokens count toward max_tokens. Interleaved thinking is the exception: there the budget covers all thinking blocks in one turn and may exceed max_tokens. Anthropic's adaptive-thinking examples use max_tokens of 16,000, and its primer advises retrying with a higher value when a response is cut off during tool use. The example below comes from Anthropic's API primer:

import anthropic

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)

Code written for OpenAI and pointed at Claude through the compatibility base URL https://api.anthropic.com/v1/ can keep either name, since Anthropic lists both max_tokens and max_completion_tokens as fully supported there. The same page warns that temperature below 1 returns a 400 error on Claude 4.7 and later models, a separate trap covered in our guide to the "Unsupported parameter: temperature" error.

··········

GEMINI API: MAXOUTPUTTOKENS, MAX_OUTPUT_TOKENS AND THE OPENAI-COMPATIBLE ENDPOINT.

Gemini has two native interfaces, and each spells the limit its own way. The generateContent API, which Google now labels legacy, takes maxOutputTokens inside generationConfig in REST calls and reports the end of a capped response with finishReason MAX_TOKENS. The Interactions API takes max_output_tokens inside generation_config. Google's thinking documentation describes the limit as the maximum number of tokens a response can generate "including thought tokens" and calls it "a hard cutoff enforced by the infrastructure".

The practical consequence is the same as on OpenAI. When the cap is reached during reasoning, Google says the response "returns truncated or empty output (while still billing for any thinking tokens generated)", and it recommends lowering thinking_level instead of setting a small limit. Gemini 4 models require thinkingLevel and no longer use thinkingBudget, while the usage data reports thinking separately in thoughtsTokenCount on generateContent and total_thought_tokens on Interactions. The example below is taken from Google's Interactions documentation:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Summarize the trade-offs of microservices.",
    generation_config={
        "thinking_level": "low",
        "max_output_tokens": 8192,
    },
)

print(interaction.output_text)
print("Thought tokens:", interaction.usage.total_thought_tokens)

On the OpenAI-compatible endpoint at https://generativelanguage.googleapis.com/v1beta/openai/, Google documents how reasoning_effort maps to Gemini thinking levels and budgets but does not document the token-limit fields. If no reasoning_effort is sent, Gemini applies the model's default level, so a small max_tokens can be consumed by thinking before any text appears. For Gemini-specific failures that look like limits, our pages on the Gemini API 503 high-demand error and on current model names, aliases and retired IDs cover the neighboring problems.

··········

DOCUMENTED RULES VERSUS USER REPORTS FOR TOKEN LIMITS.

A few points rest on forum answers or single reports, so the table marks which ones to test in your own account.

........

Point	Status	Where it comes from
max_tokens deprecated and incompatible with o-series models	Documented	OpenAI Chat Completions reference
Reasoning tokens count toward max_completion_tokens and max_output_tokens	Documented	OpenAI API reference and reasoning guide
Reserve at least 25,000 tokens for reasoning and output when starting	Documented recommendation	OpenAI reasoning guide
GPT-5 series reasoning models use max_completion_tokens on Azure	Documented	Microsoft Foundry chat completions article
Silent Azure model upgrade triggers the error on an old deployment name	Reported, confirmed in one accepted thread	Microsoft Learn Q&A, March 2026
Claude compatibility layer accepts both names	Documented	Anthropic OpenAI SDK compatibility page
Gemini thinking tokens count toward the output cap	Documented	Google thinking documentation
Gemini OpenAI endpoint treats max_tokens as a cap on thinking plus output	Forum answer, not in Google's docs	Google AI Developers Forum, September 2026
Gemini totals exceeding maxOutputTokens	Single user report, unconfirmed	Google AI Developers Forum, September 2026

........

The last row is the one to watch. In September 2026 a developer reported repeated gemini-3.8-flash runs where thinking and output together reached about twice maxOutputTokens, which contradicts both the forum answer and Google's documentation. Until Google addresses it, billing alerts should rely on the usage fields returned with each response rather than on the configured limit.

··········

HOW TO SIZE THE TOKEN LIMIT ON REASONING MODELS WITHOUT EMPTY ANSWERS.

Renaming the field removes the 400 error, but keeping the old number often replaces it with blank or cut-off answers. On every reasoning model in the table, hidden thinking is spent from the same budget as the reply, and all three providers bill those tokens as output. OpenAI's own starting point is to reserve at least 25,000 tokens and tune down once you know how much reasoning your prompts need; Anthropic's examples sit at 16,000 tokens with adaptive thinking; Google points to a lower thinking level as the better lever than a tight cap.

OpenAI returns reasoning_tokens inside completion_tokens_details and Gemini returns thoughtsTokenCount or total_thought_tokens, so a log of a few hundred real requests shows how much of each limit goes to thinking. Our overview of the Claude API models, limits and developer features covers the Anthropic side in more depth.

··········

CHOOSING THE TOKEN-LIMIT PARAMETER FOR OPENAI, CLAUDE AND GEMINI: SPECIFIC CONCLUSIONS.

On OpenAI, max_tokens survives only as a deprecated name: reasoning models on Chat Completions need max_completion_tokens, and the Responses API needs max_output_tokens. On Claude's native API, max_tokens remains the only length field and every request should carry it, while the OpenAI-compatible layer accepts either name. On Gemini, the field is maxOutputTokens in generateContent and max_output_tokens in Interactions, and the OpenAI-compatible endpoint has no documented mapping for max_tokens.

The error itself is a naming problem with a one-line fix, and the real work starts after the rename. Every one of these limits now includes reasoning, so a value chosen for visible text alone produces empty or truncated answers that still cost money. Log the stop signal and the reasoning token count on each response, raise the limit or lower the reasoning effort accordingly, and check Azure deployments and third-party libraries whenever the error appears without a code change.

··········

·····

DATA STUDIOS

·····

datastudios.org