OpenAI Chat Completions 400 Bad Request: Causes and Fixes

How do I see the real error behind an OpenAI chat completions 400 bad request?

A 400 from OpenAI always carries a JSON body shaped like {"error": {"message", "type", "param", "code"}}. Many HTTP clients raise a generic exception such as 'HTTPError: 400 Client Error: Bad Request' and hide it, so print the body first and guess later.

The type is usually invalid_request_error. The param field names the offending field (for example messages or max_tokens), which often solves the problem on its own.

# requests
r = requests.post(url, headers=headers, json=payload)
if not r.ok:
    print(r.status_code, r.text)   # full error JSON

# openai SDK (v1+)
import openai
try:
    client.chat.completions.create(**payload)
except openai.BadRequestError as e:
    print(e.status_code, e.body)       # dict with message, param, code
    print(e.response.text)             # raw body

// Node (openai package)
try { await client.chat.completions.create(payload) }
catch (e) { console.log(e.status, e.error, e.message) }

// Node fetch
const res = await fetch(url, opts);
if (!res.ok) console.log(res.status, await res.text());

# curl: -i shows headers and body; drop -f, which hides the body
curl -i https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" -d @body.json

Which error message means what? (diagnosis table)

Match the message text to the row. Exact wording varies slightly between API versions, but the key phrases are stable.

Why does the chat model say it is not supported in v1/completions?

OpenAI exposes different endpoints with different payload shapes, and each model family is tied to one or more of them. Sending gpt-3.5-turbo to /v1/completions, or text-davinci-003 to /v1/chat/completions, fails at validation with a 400.

text-davinci-003 and the other original GPT-3 completion models were retired in January 2024, so copied snippets using them now fail with a model error regardless of endpoint.

How do I migrate from completions to chat completions?

Three things change: the URL, the request body (prompt becomes messages), and the response path (choices[0].text becomes choices[0].message.content). Streaming chunks put text in choices[0].delta.content, and the first or last chunk's delta may have no content key, so guard for it.

Parameters best_of, echo and suffix do not exist on chat. Logprobs is a boolean plus top_logprobs (an integer) instead of an integer count.

1. Change the endpoint to /v1/chat/completions (or client.chat.completions.create).
2. Wrap the old prompt as {"role": "user", "content": prompt}; put standing instructions in a system message (developer on newer models).
3. Delete best_of, echo, suffix; convert logprobs to logprobs: true plus top_logprobs.
4. Read choices[0].message.content instead of choices[0].text.
5. Rename max_tokens to max_completion_tokens if the model is a reasoning model.

# BEFORE (legacy, retired)
resp = openai.Completion.create(
    model="text-davinci-003",
    prompt="Summarize: ...",
    max_tokens=200, temperature=0.2)
text = resp["choices"][0]["text"]

# AFTER (openai >= 1.0)
from openai import OpenAI
client = OpenAI()   # reads OPENAI_API_KEY
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Summarize: ..."}],
    max_tokens=200, temperature=0.2)
text = resp.choices[0].message.content

# Streaming
for chunk in client.chat.completions.create(model="gpt-4o-mini",
        messages=[{"role":"user","content":"Hi"}], stream=True):
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

What does a minimal working request look like in curl and Node?

Start from a request that is known good, then add your parameters one at a time. The first one that returns 400 is your culprit, and its error body names the param.

curl -i https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Say hello"}]
  }'

# Node (openai v4+)
# import OpenAI from "openai"; const client = new OpenAI();
# const r = await client.chat.completions.create({
#   model: "gpt-4o-mini",
#   messages: [{ role: "user", content: "Say hello" }] });
# console.log(r.choices[0].message.content);

Why does my JSON break, and how do I check context length and auth?

Building the body with string concatenation fails when the prompt contains quotes, backslashes or newlines, producing 'could not parse the JSON body'. Use json.dumps, JSON.stringify or the SDK, and in shell write the body to a file. Log the exact serialized body you send, since that is what the server sees.

The context error counts input tokens plus max_tokens (output reservation) against the window. Count input with tiktoken, then leave headroom.

Types matter: temperature must be a number, n and max_tokens integers, messages a non-empty array, and content a string or an array of typed parts (text, image_url, input_audio) only on models that accept them. Sending an image part to a text-only model is a 400.

import json, tiktoken

messages = [{"role": "user", "content": 'He said "hi"\nnew line'}]

# Serialize the same list you count below, so counted and sent content match
body = json.dumps({"model": "gpt-4o-mini", "messages": messages})

enc = tiktoken.encoding_for_model("gpt-4o-mini")
# m["content"] is a string only for plain-text messages. If content is an
# array of parts (text, image_url, ...), extract the text parts first.
prompt_tokens = sum(len(enc.encode(m["content"])) for m in messages)
# add ~4 tokens per message of overhead; keep prompt_tokens + max_tokens < window

How do I tell 400 from 401, 404 and 429 quickly?

The status code tells you which layer failed, so you can skip the wrong checklist.