How to Fix Claude API 400 Bad Request Error

The Claude API returns an HTTP 400 (Bad Request) error when your request payload contains invalid parameters, syntax errors, or fails to meet the structural requirements of the Messages API. Unlike server-side errors, a 400 error indicates that the Anthropic server understood your connection but rejected the request content before attempting processing.

Use this step-by-step troubleshooting guide to identify and fix the formatting errors causing your Claude API 400 failures.

Step 1: Verify Message Alternation (User and Assistant Roles)

Claude's Messages API enforces a strict alternating pattern between user prompts and model responses. Your message array must follow these rules:

1. The first message in the array must have the user role.
2. You cannot have two consecutive messages with the same role (e.g., user followed immediately by user).
3. The last message in the array should typically have the user role unless you are prefixing Claude's response, in which case it must be assistant.

Incorrect Structure (Triggers 400): `json [ {"role": "user", "content": "Hello"}, {"role": "user", "content": "Can you write a poem?"} ] `

Correct Structure: `json [ {"role": "user", "content": "Hello. Can you write a poem?"} ] ` Combine multiple consecutive inputs from the same speaker into a single message object before dispatching the API call.

Step 2: Move System Prompts Out of the Messages Array

If you are migrating your codebase from OpenAI's API to Anthropic's API, you might have put your system instructions inside the messages array using a system role. Anthropic does not support this structure and will throw a 400 Bad Request error.

To resolve this, extract system-level instructions and place them into the top-level system parameter of your request payload.

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

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

Step 3: Validate Required Parameters and Types

Ensure that you are passing all mandatory fields and that their data types are correct. A missing or mistyped parameter will trigger a validation failure.

1. model: Must be a valid, active Claude model string (e.g., claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022). Watch out for typos.
2. max_tokens: This is a required parameter in the Messages API. It must be an integer greater than 0. If you omit max_tokens, the API will return a 400 error immediately.
3. messages: Must be a non-empty array of objects containing role and content fields.

Double-check that you are not passing unsupported legacy parameters like prompt instead of messages, or max_tokens_to_sample which was deprecated with the older Text Completions API.

Step 4: Format Image and Document Base64 Data Correctly

When sending multimodal requests (such as images or PDFs) to Claude, check that the data structures conform to Anthropic's exact schema. Incorrect media configurations or malformed base64 strings trigger 400 errors.

1. The payload content field must be structured as an array of objects rather than a simple string. 2. Ensure your image data format matches the required structure: `json { "role": "user", "content": [ { "type": "image", "source": { "type": "base64", "media_type": "image/jpeg", "data": "/9j/4AAQSkZJRg..." } }, { "type": "text", "text": "Describe this image." } ] } ` 3. Do not include data URI headers (like data:image/jpeg;base64,) inside the data field. Only supply the raw, unadorned base64 string.

When to escalate

If you have corrected your payload structures and verified your message alternation rules but continue to receive 400 Bad Request errors, check the body of the HTTP response. The Claude API returns a JSON error payload containing a detailed message field indicating the exact validation failure. Review this message to identify the offending field. If the error message is ambiguous, contact Anthropic Support via your developer console with the unique request ID found in your response headers (request-id).