anthropic api 422 error

An HTTP status code 422 (Unprocessable Entity) indicates that while your API request reached Anthropic's servers and used valid JSON, the content of your payload violated the platform's validation rules. This usually points to formatting mistakes inside your messages or parameter conflicts. Here is how to correct your request structure.

1. Verify model name strings

Anthropic frequently updates its model registry and deprecates older identifiers. Using an incorrect or legacy model identifier (for example, mixing up Claude 3 and Claude 3.5 naming conventions) will trigger a 422 validation error. Double-check the official model list and ensure you are passing the precise string required, such as claude-3-5-sonnet-20241022.

2. Extract system prompts from the messages array

Unlike other LLM providers who accept system instructions as an object inside the messages array, Anthropic requires system prompts to be passed as a top-level parameter called system. Placing a message with the role set to 'system' inside your main message sequence will result in an immediate 422 failure. Move your system instructions to the root of the JSON payload.

3. Enforce strict role alternation

Claude expects the conversation history in the messages array to strictly alternate between the user and assistant roles. If your code appends two user queries back-to-back or begins the conversation array with an assistant message, the API will refuse to process the payload. Always normalise your history list before dispatching the call.

4. Remove unsupported parameters

Ensure your payload does not include parameters that are unsupported by the Messages API, such as outdated temperature boundaries or legacy parameters from the deprecated Text Completions API. If the request is well-formed but you receive temporary server failures instead, the endpoint might be struggling under heavy load; read our guide on how to handle the Anthropic API 529 Overloaded Error for mitigation strategies.

5. Validate nested block structures

When using multi-modal capabilities (such as uploading images) or structured tool use, the nested blocks within your message object must match the required schema exactly. Ensure that each image block contains a valid base64 string, correct media type (e.g., image/jpeg), and proper JSON structure. Any missing sub-properties will trigger a validation rejection.