How to Fix OpenAI API Error 400 Bad Request

An OpenAI API HTTP 400 Error (Bad Request) means the OpenAI servers rejected your API call because the payload contains invalid syntax, unsupported parameters, or structurally incorrect data. Unlike authentication errors (401) or rate limits (429), a 400 error is strictly a client-side configuration problem.

To resolve this error and restore your integration, work through the following troubleshooting steps systematically.

Step 1: Validate the Model Name

One of the most common causes of a 400 Bad Request error is passing an invalid or deprecated model name in your API call. OpenAI frequently deprecates older models and introduces new naming conventions.

1. Check for Deprecated Models: Models like text-davinci-003 or older legacy instruct models have been fully shut down. Attempting to call them now will result in an immediate 400 error.
2. Verify Naming Conventions: Ensure you are using current active models such as gpt-4o, gpt-4-turbo, or gpt-3.5-turbo.
3. Case Sensitivity: Model names are case-sensitive and must be entirely lowercase. Writing GPT-4 instead of gpt-4 will trigger validation failures.

Step 2: Check Payload Syntax and Data Types

The OpenAI API expects a strictly structured JSON payload. Any deviation in data types or structure will cause the server to reject the request.

1. Verify Parameter Data Types:
2. Temperature: Must be a float between 0 and 2. Passing a value outside this range, or sending it as a string (e.g., "0.7" instead of 0.7), triggers a 400 error.
3. Max Tokens: Must be a positive integer. Passing a decimal, a negative number, or a string will fail.
4. Presence Penalty / Frequency Penalty: Must be a float between -2.0 and 2.0.
5. Validate JSON Formatting: If you are making raw HTTP requests (via curl or custom HTTP libraries), validate your JSON payload using a linter. Ensure keys are double-quoted and trailing commas are removed.

Step 3: Check Message Object Structure

When using the Chat Completions endpoint (/v1/chat/completions), the messages parameter must be structured as an array of objects.

1. Confirm Role Values: Each object in the array must contain a role and a content field. Valid values for role are: * system * user * assistant * tool (or function in legacy implementations) Using custom roles like admin, bot, or human will cause an instant 400 validation error. 2. Avoid Null Values: The content field must contain a string. If your application code dynamically passes an empty or null variable to the content field, the API validation layer will reject the request.

Step 4: Verify Token Limits and Context Window

An HTTP 400 error can occur if your input prompt, combined with the requested max_tokens value, exceeds the target model's maximum context window limit.

1. Reduce Prompt Length: If your input is too long, truncate the input text or use a model with a larger context window (e.g., migrating to gpt-4o which has a 128k context window).
2. Adjust Max Tokens: If your input prompt takes up 3,500 tokens on a 4,096-token model, and you set max_tokens to 1000, the total requested tokens (4,500) exceed the model limits, resulting in a 400 error. Lower the max_tokens value or dynamically calculate it based on input size.

Step 5: Update the OpenAI SDK

If you are using an official OpenAI SDK (Python or Node.js) and have not updated it recently, your codebase might be formatting requests using deprecated schemas or outdated endpoints.

1. Python: Run pip install --upgrade openai in your terminal. If you are migrating from the pre-v1.0.0 SDK, review OpenAI's migration guide as the syntax for client initialization changed significantly.
2. Node.js: Run npm install openai@latest or yarn add openai@latest to ensure compatibility with modern endpoints and payload structures.

When to escalate

If you have verified that your JSON payload is structurally perfect, your token count is well within bounds, and the model name is correct, but you still receive a 400 error, check the official OpenAI Status page (status.openai.com) to ensure there is no active service degradation. If all systems are normal and the error persists across different networks, contact developer support through the help widget in your OpenAI API dashboard.