How to Fix Claude API 400 Bad Request Error

An HTTP 400 Bad Request error returned by the Anthropic API indicates that your request payload is malformed or invalid. This usually manifests as an invalid_request_error in the JSON response from the server.

Because the API cannot process the structure of your payload, it rejects the call entirely before sending it to the model. Follow this step-by-step troubleshooting guide to audit your payloads, fix your syntax, and resolve the 400 error.

1. Verify the Messages API Structure

Anthropic's modern Claude models (such as Claude 3 Opus, 3.5 Sonnet, and 3.5 Haiku) require the Messages API schema. Using legacy parameters from the older Text Completions API will trigger a 400 error immediately.

* The structure must use a messages array. Every item in this array must be an object containing a role and content key. * Do not include system instructions inside the messages array. The system prompt must be defined in a top-level system string parameter, outside the messages array. * Correct structure example: `json { "model": "claude-3-5-sonnet-20241022", "max_tokens": 1024, "system": "You are a helpful assistant.", "messages": [ {"role": "user", "content": "Hello!"} ] } `

2. Check the Conversational Alternation Rule

The Messages API enforces strict conversational structures. If your arrays violate these structural rules, the server returns a 400 error. Check your array validation logic:

• Role Alternation: The messages array must strictly alternate between the user and assistant roles. You cannot have two user blocks or two assistant blocks consecutively.
• Start Role: The conversation array *must* start with a user role message. You cannot begin the messages array with an assistant role message.
• Empty Elements: Ensure no items in the messages array have empty content strings. If you pass an empty string, or an object missing content completely, the API rejects the request.

3. Validate Headers and Versioning

Using manual HTTP libraries (like cURL, Axios, or requests) instead of the official SDKs requires manually constructing headers. Missing or incorrect headers are a common cause of 400 bad requests.

Verify that your request includes the following three mandatory headers:

1. x-api-key: Must contain your valid API key string.
2. anthropic-version: Must be set to a supported API version date. As of now, this is typically 2023-06-01.
3. content-type: Must be set explicitly to application/json.

If you use the official Python (anthropic) or TypeScript (@anthropic-ai/sdk) libraries, these headers are handled automatically under the hood.