Fix API 400 Unsupported Role Errors Without Breaking System Prompts
Start with the final outbound request. Use the instruction field and message positions supported by that exact endpoint, preserve tool-call pairs, and verify the full task after the role error clears.
On this page

If you receive 400 with role 'system' is not supported on this model, find the rejected message in the final request sent to the server, then repair its field or position using that endpoint's contract. For native Anthropic Messages, initial instructions belong in top-level system. For OpenAI Responses, use instructions or supported message items. For Chat Completions, use the instruction role supported by the selected model and provider.
Do not replace every system with user or developer. That can remove the error while changing who controls the assistant, when a rule takes effect, or how tool results reach the model. Anthropic now also supports mid-conversation system messages on specified models and in specified positions; a blanket “only user and assistant are allowed” rule is no longer correct for all native Messages requests. Anthropic message placement, OpenAI instruction roles.
| What the error identifies | Start with this repair |
|---|---|
Initial system inside native Anthropic messages | Put the initial operator instructions in top-level system; retain conversation turns in messages |
A later Anthropic system message | Check model support and its position, including any unfinished tool-call pair |
OpenAI-style system or developer rejected | Check the exact endpoint, model, and adapter before choosing an instruction role or field |
tool or legacy function rejected | Restore the endpoint's tool-result format and matching call ID |
| A role you never added | Inspect the framework's serialized request and the gateway's upstream conversion |
A role-specific validation error gives you a request-format problem to investigate. Repeating the same rejected body, rotating keys, or changing billing settings does not repair that format. The steps below are documented request templates and diagnostic checks; they are not reports of live API or client tests.
Decode the Error Payload Before You Change Code
Save the literal error message, status, type, code, request ID, and param when present. An OpenAI-style response may identify messages[0].role. An Anthropic-style invalid_request_error may instead name a discriminator or position in its message and provide a request ID. Do not assume every provider supplies param.
If the error says:
request.messages.1.role: invalid discriminator value.
Expected 'user' | 'assistant'inspect the second serialized message, because the index is zero-based. That expected-role list describes the validator reached by this request. It does not establish the capabilities of every model, another endpoint, or a newer native API.
Record the request destination alongside the error: provider, base URL and path, model or deployment name, API version where applicable, and the actual client and adapter versions. Then inspect the object after framework transformations. An application can start with a user message while its agent framework adds an instruction message or its provider adapter changes the format.
Use a structural diagnostic record rather than dumping private prompts:
{
"endpoint": "POST /v1/messages",
"model": "your-selected-model",
"client_version": "record-the-running-version",
"has_top_level_system": true,
"message_shapes": [
{ "index": 0, "role": "user", "block_types": ["text"] },
{ "index": 1, "role": "system", "block_types": ["text"] }
]
}This is a log example, not an API request body. Add the presence of tool-call IDs and the relevant ordering if tools are involved. Keep authorization headers, cookies, customer text, private instructions, and tool output out of the diagnostic record. If a gateway transforms the body again, distinguish the client request from the upstream request when that information is available.

Choose the Repair by Endpoint, Not by Habit
An “OpenAI-compatible” label does not identify the protocol used by every request. /v1/chat/completions, /v1/responses, and /v1/messages have different bodies. Azure deployments and provider gateways can add their own model and version constraints.
The examples below show JSON bodies for the named endpoints. Replace the model placeholder with a model supported by your existing route; keep that route's required headers and authentication. They illustrate field placement without switching your account, model, or provider.
Native Anthropic: initial instructions go in top-level system
For an initial system prompt, a minimal native POST /v1/messages body is:
{
"model": "your-selected-claude-model",
"max_tokens": 128,
"system": "Classify API errors. Give one sentence with the next diagnostic action.",
"messages": [
{ "role": "user", "content": "The request rejects messages[0].role." }
]
}Move the initial instruction text out of messages into this top-level field; leave the user's task in its user turn. Do not add OpenAI's developer role or Responses' instructions field to a native Anthropic body. Working with Messages, Messages API reference.
Later instructions require a different decision. As checked on October 6, 2026, Anthropic's detailed guide lists mid-conversation system-message support for Fable 5.1, Mythos 5.1, Fable 5, Mythos 5, Opus 5.5, Opus 4.8, Opus 5, and Sonnet 5.5 on the Claude API, Amazon Bedrock, and Google Cloud. It excludes Sonnet 5. Plain mid-conversation text does not require a beta header, but a compatible gateway or older SDK may still lack support. Use the guide's model list for your actual model rather than assuming that every Claude model accepts it. Availability and limits. As of November 10, 2026, the same list also names Fable 5.2 and Mythos 5.2, released on November 9, 2026, and now starts with them.
A supported later rule can appear after a user message and at the end of the array:
{
"model": "your-mid-conversation-system-supported-model",
"max_tokens": 128,
"system": "You are a support assistant. Keep customer data private.",
"messages": [
{ "role": "user", "content": "Classify a rejected system role." },
{ "role": "assistant", "content": "Check the request's instruction field and message placement." },
{ "role": "user", "content": "Now classify a rejected tool result." },
{ "role": "system", "content": "For subsequent answers, include the tool-call ID check." }
]
}The last rule takes effect for the next response. Moving it into the initial top-level prompt would change its timing. Keep stable rules at the top level and preserve later operator rules at their intended point when the route supports them.
The placement requirements matter even on supported models: the system message must follow a user message, including one containing a tool result, or an assistant message ending in a server-tool result; the next message must be an assistant message or the system message must end the array. It cannot be the first message or split an assistant tool_use from its user tool_result. Consecutive system messages are evaluated as a group for placement. Placement rules.
There is a documentation inconsistency worth knowing if two official pages seem to disagree: the Messages reference still contains prose saying there is no input system role, while its role enum includes system and the detailed guide explicitly documents conditional support. Follow the detailed model-and-position rules for later messages; the initial top-level system rule remains consistent. A wrapper that validates only user and assistant may reject the body before it reaches a capable native model. Reference, detailed guide.
OpenAI Chat Completions: use the supported instruction role
For a current Chat Completions model and route that support developer, use:
{
"model": "your-selected-model",
"messages": [
{ "role": "developer", "content": "Classify API errors and give one diagnostic action." },
{ "role": "user", "content": "The server rejected an outbound message role." }
]
}OpenAI's reference documents developer instructions for newer models and also documents system messages. Check the selected model's contract before replacing a rejected role. If a gateway rejects developer, establish whether its supported instruction role is system, whether it exposes a separate instruction field, or whether the selected adapter is using the wrong protocol. Chat Completions request reference.
For Azure, use the deployment and API contract you actually call. Microsoft's current reasoning guide supports system for migration on the listed newer reasoning models and says not to combine system and developer in the same request. “Azure never accepts system” and “older Azure always rejects developer” are both too broad. Do not add both roles as a compatibility experiment. Azure reasoning models.
OpenAI Responses: send needed instructions on each continued request
For POST /v1/responses, this is a minimal body:
{
"model": "your-selected-model",
"instructions": "Classify API errors and give one diagnostic action.",
"input": "The server rejected an outbound message role."
}Responses uses input items rather than the Chat Completions messages body. It also accepts compatible message items, so choosing instructions is not a reason to flatten conversation history or discard tool and reasoning items. Messages-to-items migration.
When continuing with previous_response_id, the previous response's instructions are not carried forward. Send the instructions needed for the new response again:
{
"model": "your-selected-model",
"previous_response_id": "resp_replace_with_the_prior_response_id",
"instructions": "Classify API errors and give one diagnostic action.",
"input": "Now check the tool-result format."
}History linkage and instruction inheritance are different features. A continuation that returns text but silently loses the operator's rules is not a completed repair. Instruction scope.
Fix Each Role Branch Without Losing the Original Intent
For system or developer, preserve both authority and timing. An initial application policy should remain in a supported instruction surface. A later operator update should take effect at the intended point, rather than being copied into every historical user turn or applied retroactively from the initial prompt.
If the destination supports only ordinary user messages and offers no equivalent instruction surface, renaming the role cannot preserve the original hierarchy. Select a supported protocol or adapter that can carry the policy. Treat any fallback that lowers instruction priority as a deliberate behavior change, not a syntax-only fix. OpenAI documents higher priority for developer instructions than user messages; Anthropic's mid-conversation guide explains how later system instructions affect future turns. OpenAI hierarchy, Anthropic later instructions.
tool and legacy function need protocol conversion, not a new label
Tool results must refer to the call that produced them. The following are continuation fragments, not complete initial requests:
| API | Result fragment | What must be preserved |
|---|---|---|
| OpenAI Chat Completions | {"role":"tool","tool_call_id":"call_example","content":"synthetic result"} | The preceding assistant's tool_calls entry with the same ID |
| OpenAI Responses | {"type":"function_call_output","call_id":"call_example","output":"synthetic result"} | The corresponding function_call and its call_id, plus required continuation items |
| Native Anthropic Messages | {"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_example","content":"synthetic result"}]} | The immediately preceding assistant tool_use block with the same ID |
Chat Completions' legacy function format uses its own fields, including the function name. Renaming function to tool does not create a missing tool_call_id; renaming tool to user does not convert an OpenAI transcript into Anthropic tool blocks. Chat Completions tool messages, Responses item conversion.
For Anthropic client tools, place results immediately after the assistant tool-use message, with all tool_result blocks before any ordinary text in that user message. Do not insert a system update between the call and its result. Server-tool continuations have their own requirements; follow the relevant continuation branch rather than rebuilding it as a client tool call. Handling Anthropic tool calls.

Preserve valid assistant history, thinking blocks, signatures, call IDs, and result ordering when fixing an adapter. Deleting all history may conceal the rejected role while losing the work the agent had already performed. Anthropic also documents thinking-verification constraints for newer models: rewriting earlier messages can affect later verification. Retrieved pages, customer text, and tool output should remain data in their appropriate blocks, not be promoted into operator instructions. History and thinking limits.
If the role is missing, null, capitalized incorrectly, or serialized as an enum name instead of its wire value, fix that construction bug. Validate against the selected endpoint's schema; do not enforce one global role whitelist across all providers.
Frameworks Can Add the Failing Role After Your Code Looks Correct
Compare the framework's final body with the minimal body for the same endpoint. Inspect its default system prompt, memory or reminder insertion, tool conversion, and any compatibility adapter. The component that constructs the rejected object is the component to repair.
Claude Code provides a useful example of why the exact error matters. Its current error reference distinguishes incorrect system-message placement from a client version that does not recognize newer message handling, and separately documents model-specific minimum client versions. Those are different branches from a provider simply rejecting a role enum. A one-time conversion of a client reminder to user text is not a general rule for lowering the initial system prompt's priority. Claude Code error reference.
A May 2026 Claude Code issue includes different outcomes across desktop and CLI versions, models, and provider routes. Commenters reported upgrades or historical rollbacks that helped their particular setup. Those reports establish that client and route differences can matter; they do not identify one currently correct version or prove a universal cause.
Compare the running client binary and adapter with the recorded failing setup. If a version change introduced the problem, use the affected client's documented compatibility path and repair its conversion where appropriate. Do not delete project history or assume a historical rollback number is today's fix. If the final body is unavailable, keep the generating component as an unresolved diagnostic boundary rather than claiming the model is at fault.
Verify With the Same-Route Smoke Test
Keep the provider, base URL, endpoint path, API version, model or deployment, client, and adapter fixed while changing one relevant field or position. A working direct OpenAI request does not prove a failing gateway request is repaired; a different model passing does not establish that the original model supports the same input.
- Check the body offline. Parse the JSON, confirm the field names, inspect role positions, and match tool-call IDs. Use synthetic text for examples. This catches construction mistakes without testing server acceptance.
- Check acceptance on the authorized route. Submit a minimal request that still exercises the repaired instruction or tool branch. If it receives another validation error, investigate that error; only the original role check has progressed. A
2xxresponse is an acceptance signal, not proof that the task was completed. - Check the returned behavior. Confirm the response is complete and meets the requested output, including the operator's instructions. Use a harmless conflicting user instruction to check that the application policy still holds in that example. For a later rule, check that it affects the next turn at the intended point. A small test is evidence for that case, not a guarantee across every prompt.
- Check the full application path. Restore the actual framework workflow. For tools, verify that the assistant issues the intended call, the matching result returns, and the assistant produces its final answer. Confirm the application receives and renders or stores that answer rather than abandoning the task after the first response.
With Responses continuations, include the needed instructions again. With Anthropic tools, retain the paired blocks and placement. These checks catch repairs that make a minimal text call pass but leave the coding agent's next tool turn broken.
A request ending with a model turn is a different branch
Requests ending with a model turn are not supported concerns the final turn or prefill, not necessarily a system-role mismatch. Google's current latest-model migration guide requires removing unsupported prefilled model endings and supplying a final user turn with nonempty text for the documented model. Preserve legitimate earlier model turns and follow the model's tool-response rules; do not rename the entire history to user or assume the current guide applies to every older Gemini model. Google's model migration guidance. Google states the rule itself in its Gemini 3.6 Flash change notes: from 3.6 Flash and 3.5 Flash-Lite onward, including Gemini 4 Argon, a request whose last non-empty turn is a model turn returns 400. The triggers, a dated request-shape test and per-tool fixes are in Fix "Requests ending with a model turn are not supported".
Likewise, a new error about a function's schema, oversized images, service tier, or data-retention eligibility needs its own field-specific diagnosis. Removing a role will not repair those contracts. Keep the original requested features intact while identifying the separate failure.
Escalate With Evidence, Not a Screenshot
If the minimal request still fails on the documented route, prepare a small record containing the exact endpoint, model or deployment, version information, structured request shape, response body, available request ID, and the single change you tried. Include the expected instruction placement or tool-result format and its documentation link.
If only the full application fails, include the difference between its final serialized body and the passing minimal body. That difference is more useful than a screenshot of “400” because it shows whether the issue belongs to the client, adapter, gateway conversion, or server contract. Keep private prompts and customer data out of the record.
FAQ
Should I replace system with developer everywhere?
No. Use developer only where the selected Chat Completions contract supports it. Native Anthropic initial instructions use top-level system; Responses can use instructions. Azure's current reasoning guide also supports system for the documented models and says not to combine it with developer. Azure guidance.
Can Anthropic accept system inside messages now?
Yes, for mid-conversation messages on the models listed in its current guide and with the required placement. Initial instructions still go in top-level system, and a system message cannot split a tool-use/result pair. Model support does not guarantee that an older SDK or third-party gateway accepts the same body. Anthropic support and placement.
Does previous_response_id preserve my Responses instructions?
No. It links the response history, but prior instructions are not carried into the next request. Send the operator instructions needed for that response again. OpenAI instruction scope.
Is putting the system prompt in a user message a safe fix?
It changes instruction priority. Prefer the endpoint's supported operator-instruction field or an adapter that preserves it. A request passing validation after that replacement does not show that the assistant still follows the original application policy.
Why does it still fail after my minimal request passes?
The framework may reinsert the rejected role, reconstruct tool results incorrectly, or take a different route on the next turn. Inspect the final body of the failing full workflow and verify the tool round trip and final answer, not just the first accepted request.
Sources12
External pages this guide links to, in the order they appear. Last updated Nov 10, 2026.
Sources12
External pages this guide links to, in the order they appear. Last updated Nov 10, 2026.
- 1.Anthropic message placementplatform.claude.com/docs/es/build-with-claude/mid-conversation-system-messages
- 2.OpenAI instruction rolesdevelopers.openai.com/api/docs/guides/text
- 3.Working with Messagesplatform.claude.com/docs/es/build-with-claude/working-with-messages
- 4.Messages API referenceplatform.claude.com/docs/en/api/messages/create
- 5.Chat Completions request referencedevelopers.openai.com/api/reference/resources/chat/subresources/completions/methods/create
- 6.Azure reasoning modelslearn.microsoft.com/en-us/azure/foundry/openai/how-to/reasoning
- 7.Messages-to-items migrationdevelopers.openai.com/api/docs/guides/migrate-to-responses
- 8.Handling Anthropic tool callsplatform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls
- 9.Claude Code error referencecode.claude.com/docs/ru/errors
- 10.May 2026 Claude Code issuegithub.com/anthropics/claude-code/issues/61412
- 11.Google's model migration guidanceai.google.dev/gemini-api/docs/generate-content/latest-model
- 12.Gemini 3.6 Flash change notesai.google.dev/gemini-api/docs/whats-new-gemini-3.6





