Skip to main content

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.

LaoZhang AI TeamPublishedUpdated 12 min read
On this page
An unsupported-role error is repaired by routing instructions to the appropriate API surface while preserving authority, timing, and tool pairs.

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 identifiesStart with this repair
Initial system inside native Anthropic messagesPut the initial operator instructions in top-level system; retain conversation turns in messages
A later Anthropic system messageCheck model support and its position, including any unfinished tool-call pair
OpenAI-style system or developer rejectedCheck the exact endpoint, model, and adapter before choosing an instruction role or field
tool or legacy function rejectedRestore the endpoint's tool-result format and matching call ID
A role you never addedInspect 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:

json
{
  "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.

A request pipeline traces an inserted role from the framework to the final outbound body and highlights the second serialized message for inspection.

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:

json
{
  "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:

json
{
  "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:

json
{
  "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:

json
{
  "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:

json
{
  "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:

APIResult fragmentWhat 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.

Three protocol lanes link tool calls to their matching results and final answers, with an Anthropic client-tool pair kept adjacent.

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.

  1. 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.
  2. 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 2xx response is an acceptance signal, not proof that the task was completed.
  3. 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.
  4. 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.

  1. 1.Anthropic message placementplatform.claude.com/docs/es/build-with-claude/mid-conversation-system-messages
  2. 2.OpenAI instruction rolesdevelopers.openai.com/api/docs/guides/text
  3. 3.Working with Messagesplatform.claude.com/docs/es/build-with-claude/working-with-messages
  4. 4.Messages API referenceplatform.claude.com/docs/en/api/messages/create
  5. 5.Chat Completions request referencedevelopers.openai.com/api/reference/resources/chat/subresources/completions/methods/create
  6. 6.Azure reasoning modelslearn.microsoft.com/en-us/azure/foundry/openai/how-to/reasoning
  7. 7.Messages-to-items migrationdevelopers.openai.com/api/docs/guides/migrate-to-responses
  8. 8.Handling Anthropic tool callsplatform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls
  9. 9.Claude Code error referencecode.claude.com/docs/ru/errors
  10. 10.May 2026 Claude Code issuegithub.com/anthropics/claude-code/issues/61412
  11. 11.Google's model migration guidanceai.google.dev/gemini-api/docs/generate-content/latest-model
  12. 12.Gemini 3.6 Flash change notesai.google.dev/gemini-api/docs/whats-new-gemini-3.6
More in Troubleshooting
OpenClaw Anthropic API Key Error Fix Guide showing error types and solutions
Troubleshooting

Fix OpenClaw Anthropic API Key Error: 401, Missing Auth, OAuth, and Cooldown

OpenClaw Anthropic API key errors need an owner-first read: prove whether Anthropic auth is missing, the key is rejected, OAuth cannot refresh, an env var overrides config, the selected model is unavailable, or OpenClaw is only showing a provider cooldown after an earlier failure.

18 min
A document branches into ChatGPT, the OpenAI API, and Azure or connectors to identify the rejecting upload surface.
Troubleshooting

OpenAI "File Type Not Supported"? Fix the "Try Again With a PDF" Error

If OpenAI says your file type is not supported and tells you to try again with a PDF, the useful first move is to identify the rejecting surface. Current official OpenAI docs are not blanket PDF-only, but some lagging Azure or connector paths still behave that way.

10 min