OpenAI o-Series Reasoning Tokens Exhausted
Your o1/o3 response has empty content and finish_reason: "length". Reasoning burned through max_completion_tokens before producing visible output. Increase the budget, reduce reasoning_effort, or switch to GPT-5 if you don't need deep reasoning.
Reasoning tokens count against max_completion_tokens BEFORE visible output. If reasoning uses 25K tokens and your cap is 25K, output is empty. Set generous cap: complex tasks use 10K–50K reasoning + your desired output. Start with max_completion_tokens: 32000 for o3, monitor actual usage, tune down.
The Symptoms You're Seeing
response = client.chat.completions.create(
model="o3",
max_completion_tokens=4096,
messages=[...]
)
response.choices[0].message.content = ""
response.choices[0].finish_reason = "length"
response.usage:
prompt_tokens: 1200
completion_tokens: 4096
completion_tokens_details:
reasoning_tokens: 4096 ← ALL budget used on reasoning
accepted_prediction_tokens: 0
rejected_prediction_tokens: 0
total_tokens: 5296
You paid for 4096 output tokens and got nothing visible.How max_completion_tokens Works
max_completion_tokens is the total cap on everything the model generates after your prompt — reasoning tokens (hidden) AND visible content tokens combined. If reasoning uses the full budget, no visible output is possible. Solve by budgeting explicitly: total_needed = expected_reasoning + desired_output.
Reasoning Token Budget Guide
| Task complexity | Typical reasoning tokens | Recommended max_completion_tokens |
|---|---|---|
| Simple Q&A | 500–2000 | 4,000 |
| Code debugging | 3,000–10,000 | 16,000 |
| Math problem | 5,000–20,000 | 25,000 |
| Multi-step analysis | 10,000–30,000 | 40,000 |
| Proof derivation | 20,000–50,000+ | 65,000 |
| o3 with reasoning_effort=high | 2–3× medium | Multiply above by 2–3 |
What Actually Causes This Error
Fixes That Work (Tested Nov 2026)
1Set Generous max_completion_tokens
2Adaptive Budget Based on Task
3Consider GPT-5 for Non-Reasoning Tasks
Rule of thumb: if the task involves multi-step logic where showing work matters, or complex problem-solving where the model needs to explore approaches, use o-series. For extraction, summarization, chat, RAG answers, function calls — GPT-5 is faster, cheaper, and equally reliable.
Preventing This Error Going Forward
- Never set max_completion_tokens < 4096 on o-series. Minimum viable budget.
- Log reasoning_tokens on every response. Learn your real budget needs.
- Alert when reasoning_tokens > 80% of budget. Near-miss for empty output.
- Match reasoning_effort to task complexity. Don't default to high.
- Consider GPT-5 as default; escalate to o-series. Reasoning is a specialty.
Researcher · AI Error Hub
Frequently Asked Questions
No — reasoning tokens are hidden. You see the token count in usage.completion_tokens_details.reasoning_tokens but not the content. Anthropic's Claude exposes thinking; OpenAI does not.
Yes on the request that generated them. In subsequent turns, the reasoning is discarded — only the visible content persists. So reasoning doesn't grow your context indefinitely.
max_tokens is legacy (GPT-4 and earlier); caps visible output only. max_completion_tokens covers reasoning + output for o-series. On o-series, use max_completion_tokens; on GPT-5/4o, either works but max_completion_tokens is preferred.
Rare but possible if budget is very tight. "low" uses fewer reasoning tokens (500-3000 typical) so 4096 budget usually works. When in doubt, still set 8K+.
Yes — detect finish_reason == "length" AND empty content, then retry with 2× budget. Cap retries at 2 to prevent runaway cost. Log outcome for budget tuning.