How to Fix Claude API 422 Unprocessable Entity Error

An HTTP 422 Unprocessable Entity error indicates that the Anthropic API server received your request, understood the JSON syntax, but rejected the contents of the payload because it violates validation rules. This is different from a 400 Bad Request error, which usually signals broken JSON formatting or corrupted headers.

A 422 error occurs when parameters are missing, are of the incorrect data type, or conflict with Anthropic's processing rules.

Follow these troubleshooting steps to validate and adjust your API payloads.

1. Verify Model Naming Conventions If you manually pass a model string to the API, using an outdated, typo-ridden, or unsupported model name will trigger a 422 validation error.

• Incorrect: claude-3-sonnet, claude-3.5-sonnet, claude-v3
• Correct: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229

Always consult Anthropic's official API documentation for the most current model identifiers. If you are using a third-party wrapper library, make sure it is not appending deprecated model strings to your requests.

2. Correct the Messages Array Structure The Messages API (`/v1/messages`) requires a highly structured format for chat histories. It will throw a 422 error if the structural patterns are violated:

• Role Alternation: The messages array must alternate between user and assistant roles. If you have two sequential user messages or two sequential assistant messages, the API will reject the request.
• Starting Role: The payload must always start with a message containing the user role.
• Non-Empty Messages: Message objects must contain content. Sending a message block with empty text fields or empty arrays under the content field will result in a 422 error.

Example of a structurally valid payload: `json { "model": "claude-3-5-sonnet-20241022", "max_tokens": 1024, "messages": [ {"role": "user", "content": "Hello, Claude!"}, {"role": "assistant", "content": "Hello! How can I help you?"}, {"role": "user", "content": "Can you analyze this system structure?"} ] } `

3. Position the System Prompt Correctly Developers migrating from other AI APIs often attempt to include system instructions inside the `messages` array using a role of `"system"`. The Claude API does not support a `system` role within the `messages` array and will throw a 422 error if one is detected.

Instead, define system instructions using the root-level system parameter:

`json /* WRONG */ { "model": "claude-3-5-sonnet-20241022", "messages": [ {"role": "system", "content": "You are a coding assistant."}, {"role": "user", "content": "Write a python function."} ] }

/* CORRECT */ { "model": "claude-3-5-sonnet-20241022", "system": "You are a coding assistant.", "messages": [ {"role": "user", "content": "Write a python function."} ] } `

4. Audit Parameter Limits and Types Ensure your payload parameters align with strict type and mathematical boundaries required by the validation server:

• max_tokens (Required): This value must always be present, be a positive integer, and fall within the limits of the specified model. It cannot be set to 0 or negative numbers.
• temperature: If included, this decimal value must be strictly between 0.0 and 1.0. Values exceeding 1.0 will result in validation rejections.
• top_p and top_k: Ensure top_p is within 0.0 and 1.0. Ensure top_k is a positive integer (greater than or equal to 0).

When to escalate If your request payload matches the official SDK specification exactly and you still receive a 422 error, check if your SDK library is out of date. Run an upgrade command (`npm install @anthropic-ai/sdk@latest` or `pip install --upgrade anthropic`) to make sure your SDK has the same schema validations as the server. If problems continue, query the Anthropic developer forums or contact Claude support with the complete, raw JSON request object and the associated request ID headers for assistance.