How to Fix Claude API Error 400 Bad Request

The Claude API Error 400 (Bad Request) indicates that your client sent a request that the Anthropic server could not understand or process. This is almost always a client-side issue involving invalid request payloads, malformed JSON, or structural errors in how your messages are formatted.

Unlike standard text generation APIs, Anthropic's Messages API enforces strict rules regarding how conversations are structured and how parameters are defined. When these rules are violated, the API rejects the connection with a 400 status code.

Common Causes of Claude API 400 Errors

Most 400 errors stem from a few specific implementation mistakes: * Invalid Role Sequence: The Messages API requires your message array to alternate strictly between user and assistant roles. Starting with an assistant message or passing two consecutive user messages will trigger a 400 error. * Incorrect System Prompt Placement: Including the system prompt inside the messages array under a "system" role instead of using the top-level system parameter. * Missing Required Parameters: Failing to supply mandatory fields like max_tokens or model in your request body. * Invalid Model Name: Typographical errors in the model string (e.g., using claude-3-sonnet instead of the fully specified model identifier like claude-3-sonnet-20240229).

Step-by-Step Fixes for Error 400

Follow these troubleshooting steps to identify and fix the structural issues causing the 400 Bad Request error.

Step 1: Enforce Alternating Message Roles Your `messages` array must begin with a `user` role and alternate strictly. * **Incorrect Structure:** ```json "messages": [ {"role": "user", "content": "Hello"}, {"role": "user", "content": "Can you help me write code?"} ] ``` * **Correct Structure:** ```json "messages": [ {"role": "user", "content": "Hello. Can you help me write code?"} ] ``` If you need to feed previous conversation history into the API, ensure your backend logic merges consecutive messages of the same role or injects placeholder responses where appropriate.

Step 2: Move the System Prompt to the Top Level If you are migrating code from other LLM providers, you might be accustomed to passing system instructions within the messages array. Anthropic requires system instructions to be passed in a separate top-level parameter called `system`. * **Incorrect Structure:** ```json "messages": [ {"role": "system", "content": "You are a helpful coding assistant."}, {"role": "user", "content": "Help me check this loop."} ] ``` * **Correct Structure:** ```json { "model": "claude-3-5-sonnet-20241022", "system": "You are a helpful coding assistant.", "messages": [ {"role": "user", "content": "Help me check this loop."} ], "max_tokens": 1024 } ```

Step 3: Check for Missing or Invalid Parameters Ensure that you are providing all mandatory arguments. 1. **`max_tokens`:** This parameter is strictly required for all message generation requests. It must be a positive integer. 2. **`model`:** Ensure you are using an active, supported model name. Use exact strings such as `claude-3-5-sonnet-20241022` or `claude-3-opus-20240229`. Do not truncate or invent short names.

Step 4: Validate and Clean JSON Payloads If you are sending requests via raw `curl` or custom HTTP clients rather than the official Python or TypeScript SDKs, validate your JSON output. Ensure there are no trailing commas, unescaped control characters within string blocks, or unclosed brackets. Use a JSON validator to parse your raw request payload before transmitting it.

Correct API Request Pattern (Python SDK)

Ensure your integration mirrors this verified, structurally sound setup:

`python import anthropic

client = anthropic.Anthropic()

message = client.messages.create( model="claude-3-5-sonnet-20241022", max_tokens=1024, system="You are an expert software developer.", messages=[ {"role": "user", "content": "Write a basic Python quicksort function."} ] ) print(message.content[0].text) `

When to Escalate

If you have verified that your JSON payload is perfectly formatted, your roles alternate, system prompts are placed correctly, and you still receive a 400 error, check the error.type and error.message properties in the returned JSON body. If the error code persists despite correct formatting, consult the official Anthropic Developer Console to ensure your API keys or workspace configurations haven't been corrupted, or check the Anthropic Status page for active platform issues.