How to Fix Claude API 400 Validation Error

An HTTP 400 Bad Request validation error from the Anthropic API indicates that your JSON payload is structured incorrectly or contains values that do not comply with the official API schema. The error response generally returns an invalid_request_error type.

Because Anthropic enforces a strict structural layout for its chat completions (the Messages API), even small structural discrepancies will trigger this block. Follow these steps to diagnose and correct payload validation errors.

1. Fix Alternating Message Roles Unlike other LLM providers that allow arbitrary lists of messages, the Anthropic Messages API strictly requires alternating `user` and `assistant` roles.

• Your message array must start with a user role (unless you are continuing an assistant turn, which requires pre-filling, but this is an advanced feature that still requires structural symmetry).
• You cannot have two consecutive user messages or two consecutive assistant messages.
• The last message in the array must be a user message (unless you are intentionally pre-filling an assistant response).

Incorrect Payload: `json [ {"role": "user", "content": "Hello!"}, {"role": "user", "content": "Are you there?"} ] `

Correct Payload: `json [ {"role": "user", "content": "Hello! Are you there?"} ] ` Combine sequential messages from the same sender into a single content block or string before transmitting them to the API.

2. Relocate the System Prompt Developers migrating from other LLM platforms often include system instructions inside the `messages` array using a `"role": "system"` object. Anthropic's Messages API does not accept a system role within the `messages` parameter. Including it there will prompt a `400 Validation Error`.

Instead, system instructions must be passed as a top-level parameter named system.

Incorrect Structure: `json { "model": "claude-3-5-sonnet-20241022", "messages": [ {"role": "system", "content": "You are a helpful coding assistant."}, {"role": "user", "content": "Help me write a loop." }] } `

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

3. Verify Model Names and Parameters Another frequent source of 400 errors is referencing outdated, misspelled, or deprecated model strings. Ensure you are using active model strings exactly as specified in the Anthropic documentation.

• Correct: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229
• Incorrect: claude-3-sonnet, claude-v3.5-sonnet, claude-3.5-sonnet-latest (unless using specific regional routing tags on partner clouds)

Additionally, check that parameter types match their expected schemas: * max_tokens must be a positive integer and is a required parameter in every request. * temperature must be a float between 0.0 and 1.0. * top_p or top_k must be within their valid numeric ranges.

4. Strip Empty Content Blocks and Trailing Whitespace Sending an empty string in the `content` block of a message object will trigger a validation error. If you are programmatically assembling conversational history, ensure you prune empty objects or strip out null inputs.

`json // This will trigger an HTTP 400 error { "role": "user", "content": "" } ` Before making the API call, add validation logic to filter out messages where content is null, empty, or consists only of whitespace.

When to Escalate If you have verified that your JSON payload matches the schema perfectly, are utilizing the correct SDK, and still receive an HTTP 400 validation error, check the Anthropic Status page to verify that there are no ongoing active deployments or service regressions affecting specific models. If the service is operational, open an issue on the official Anthropic GitHub SDK repository with a copy of your sanitized JSON payload.