---
title: "OpenAI API — max_completion_tokens Migration"
aliases: [openai-max-tokens, max_completion_tokens, openai-param-migration]
tags: [openai, api, llm, python, migration, wrapper]
sources:
  - "daily/2026-04-17.md"
created: 2026-04-17
updated: 2026-04-17
---

# OpenAI API — max_completion_tokens Migration

Newer OpenAI models (o-series, GPT-4.1, GPT-5.x) no longer accept `max_tokens` in the API request. The parameter was renamed to `max_completion_tokens`. Passing `max_tokens` causes an explicit API error that surfaces in two places: the raw API call site and any internal wrapper functions that forward the parameter.

## Key Points

- `max_tokens` is **rejected** by newer OpenAI models — the API returns an error, not a warning
- Error message: `'max_tokens' is not supported with this model`
- The fix must be applied in **both** direct API calls and any internal wrapper that passes `max_tokens` as a keyword argument (e.g., a `chat_structured()` helper)
- A frontend crash (e.g., `TypeError: Cannot read properties of undefined`) downstream of this error is often a symptom — the backend returned an error instead of the expected response, and the frontend tried to process `undefined`
- Always grep for `max_tokens` in both the API call layer and any utility/wrapper modules before deploying to a project using newer models

## Details

### The Error

```
openai.BadRequestError: 400 Bad Request
{'error': {'message': "'max_tokens' is not supported with this model", 'type': 'invalid_request_error', ...}}
```

This is a hard error — the API call fails, returns no completion, and the caller receives `None` or raises an exception depending on the error handling.

### Fix: Direct API Call

```python
# ❌ Old — fails on newer models
response = client.chat.completions.create(
    model="gpt-4.1",
    messages=messages,
    max_tokens=2048,
)

# ✅ New
response = client.chat.completions.create(
    model="gpt-4.1",
    messages=messages,
    max_completion_tokens=2048,
)
```

### Fix: Internal Wrappers

Any wrapper function that accepts and forwards `max_tokens` must also be updated:

```python
# ❌ Old wrapper
def chat_structured(messages, schema, max_tokens=2048):
    return client.chat.completions.create(
        ...,
        max_tokens=max_tokens,  # fails
    )

# ✅ New wrapper
def chat_structured(messages, schema, max_completion_tokens=2048):
    return client.chat.completions.create(
        ...,
        max_completion_tokens=max_completion_tokens,
    )
```

If the wrapper is used across multiple call sites, update the parameter name in callers too — or keep the old kwarg name in the function signature but map it internally for backwards compatibility.

### Finding All Affected Call Sites

```bash
# Find every location that passes max_tokens
grep -rn "max_tokens" app/ --include="*.py"

# Common locations:
# - Direct client.chat.completions.create() calls
# - Wrapper functions like chat_structured(), llm_call(), generate_text()
# - Any function that accepts **kwargs and forwards to OpenAI
```

### Frontend Symptom

If the backend API returns an error instead of the expected JSON, frontend JavaScript that tries to process the response will crash with a TypeError on `undefined`:

```
TypeError: Cannot read properties of undefined (reading 'split')
```

This appears in minified bundles as a stack trace pointing to the component that processes the LLM response (e.g., `VariantsGrid.tsx`). Fixing the backend error resolves the frontend crash — the frontend null-guard is optional hardening, not the root fix.

### Model Compatibility

- Models that still accept `max_tokens`: GPT-3.5-turbo, GPT-4 (original), some fine-tuned variants
- Models that require `max_completion_tokens`: o1, o3, GPT-4.1, GPT-5.x and later
- When in doubt, use `max_completion_tokens` — older models that don't recognize it may silently ignore it, which is preferable to a hard error

## Related Concepts

- [[wiki/concepts/fastapi-mongodb-role-migration]] — FastAPI backend patterns where LLM wrappers live
- [[wiki/llm-models/_index]] — model catalog for identifying which models require the new parameter
- [[wiki/tech-patterns/_index]] — AI tech pattern articles covering OpenAI integration

## Sources

- [[daily/2026-04-17.md]] — Barclays banner builder app on optical-dev.oliver.solutions; `max_tokens` error surfaced during Barclays Rainy Day Saver brief testing; fix applied to both direct API call and `chat_structured()` wrapper; deployed with `bash deploy.sh --skip-frontend`
