How to Fix Claude API 400 Bad Request Error

An HTTP 400 Bad Request error indicates that the Claude API rejected your request because the server could not understand or validate your payload structure. Unlike 401 (Unauthorized) or 429 (Rate Limit) errors, a 400 error points directly to syntactical or logical issues within your code’s request payload.

This guide outlines the most common causes of 400 bad_request_error exceptions in the Messages API and details how to fix them.

1. Correct the Message Roles and Order The Messages API enforces strict rules regarding how conversations are formatted. If you violate these rules, the API throws a 400 error. Check your `messages` array for the following:

• Alternate Roles: Messages must strictly alternate between user and assistant. You cannot send two consecutive user messages or two consecutive assistant messages.
• Start with User: The conversation list must begin with a user role message. It cannot start with an assistant role message.
• Non-Empty Content: Every message block in the array must contain a non-empty content field. Sending an empty string or an empty array as content will trigger a validation error.

Incorrect Payload: `json { "model": "claude-3-5-sonnet-20241022", "messages": [ {"role": "assistant", "content": "How can I help you?"}, {"role": "user", "content": "Analyze this text."} ] } `

Correct Payload: `json { "model": "claude-3-5-sonnet-20241022", "messages": [ {"role": "user", "content": "Analyze this text."} ] } `

2. Separate System Prompts from the Messages Array A frequent point of confusion is how system instructions are declared. In other LLM APIs, system instructions are passed as a message object inside the conversation array (`{"role": "system"}`). In the Anthropic Claude Messages API, **this is invalid and causes a 400 error.**

System prompts must be placed in a top-level system parameter outside the messages array.

Incorrect Format: `json { "model": "claude-3-5-sonnet-20241022", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ] } `

Correct Format: `json { "model": "claude-3-5-sonnet-20241022", "system": "You are a helpful assistant.", "messages": [ {"role": "user", "content": "Hello!"} ] } `

3. Validate Parameters and Model Names Passing unsupported parameters or incorrect data types to the API payload immediately results in a 400 Bad Request error. Check the following:

• Model Strings: Ensure your model parameter matches an active Claude model identifier exactly (e.g., claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, or claude-3-opus-20240229). Do not use deprecated model strings like claude-v2.1 or legacy aliases.
• Data Types: Verify parameter types. max_tokens must be an integer, not a string (e.g., 1024, not "1024"). temperature must be a float between 0.0 and 1.0.
• Stop Sequences: If you are using the stop_sequences array, ensure it contains only strings. Passing an empty array or non-string values will break validation.

4. Check JSON Structure and Character Escaping If you are sending raw HTTP requests using tools like `curl` or manual HTTP clients rather than the official Python/Node SDKs, unescaped control characters in your JSON payload will break parsing.

• Validate your JSON body using a linter before sending it.
• Ensure that newlines inside user queries are properly escaped as \n.
• Ensure quotation marks inside string fields are escaped as \".

`bash # Example of a correctly structured raw cURL call curl https://api.anthropic.com/v1/messages \ --header "x-api-key: your-api-key-here" \ --header "anthropic-version: 2023-06-01" \ --header "content-type: application/json" \ --data '{ "model": "claude-3-5-sonnet-20241022", "max_tokens": 1024, "messages": [{"role": "user", "content": "Analyze line 1.\nAnalyze line 2."}] }' `

When to escalate If you have verified that your JSON layout is compliant, roles alternate correctly, parameters are typed accurately, and you still receive a 400 error, check the Anthropic API Status Page to see if there is an active incident. If services are normal, log the response body (which contains specific error sub-types like `invalid_request_error`) and contact Anthropic Support via the Developer Console.