시스템 지시를 깨지 않고 API 400 role 미지원 오류를 고치는 방법

400과 함께 role 'system' is not supported on this model이 나오면 서버로 전송된 최종 요청에서 해당 역할이 어느 필드, 어느 위치에 들어갔는지부터 확인합니다. system을 모두 user로 바꾸면 오류가 사라질 수 있지만, 애플리케이션의 지시가 사용자 입력과 같은 우선순위로 내려갑니다. 정상 응답을 받는 것과 원래 작업을 올바르게 수행하는 것은 다릅니다.

수정할 곳은 실제 API에 따라 달라집니다. Anthropic Messages의 대화 시작 지시는 최상위 system 필드에 둡니다. OpenAI Chat Completions는 선택한 모델이 지원하는 system 또는 developer 메시지, Responses는 instructions 등을 사용합니다. Anthropic의 대화 중간 system 메시지는 현재 일부 모델에서 지원되므로, 무조건 금지된 역할로 처리해서도 안 됩니다.

아래 예시는 2026년 10월 6일 확인한 공식 문서에 따른 요청 구조입니다. 모델 ID와 응답 ID는 설명용 자리표시자이며, 실제 계정에서 API를 호출해 복구를 입증한 예시는 아닙니다.

오류 원문과 최종 요청에서 문제 위치 찾기

먼저 전체 오류 본문을 확인합니다. message에 거부된 역할이 있는지, param이 messages[0].role처럼 특정 위치를 가리키는지 봅니다. param이 없는 응답도 있으므로 필드가 없다고 역할 오류를 배제하지 않습니다. 함께 받은 type, code, 요청 ID도 보관하면 어느 서버가 거부했는지 확인하기 쉽습니다.

다음으로 프레임워크와 어댑터 변환을 마친 요청을 봅니다. 코드에 user만 작성했어도 메모리, 기본 프롬프트, 도구 정책을 붙이는 단계에서 system이 추가될 수 있습니다. 게이트웨이가 OpenAI 형식을 Anthropic 형식으로 변환하는 경우에는 변환 전 배열만 보고 판단할 수 없습니다.

프롬프트 원문까지 로그에 남길 필요는 없습니다. 역할과 콘텐츠 종류만 추출하고, API 키·인증 헤더·고객 입력·비공개 지시·도구 결과 원문은 제외합니다. 다음은 전송 직전 JSON을 이미 확보한 경우에 사용할 수 있는 오프라인 확인 코드입니다. 네트워크 요청을 보내지 않으며, 공급자별 유효성 검사도 대신하지 않습니다.

function describeRequest(body) {
  const messages = Array.isArray(body.messages) ? body.messages : [];
  return {
    model: body.model ?? null,
    hasSystemField: Object.hasOwn(body, "system"),
    hasInstructionsField: Object.hasOwn(body, "instructions"),
    hasPreviousResponseId: Object.hasOwn(body, "previous_response_id"),
    messages: messages.map((message, index) => ({
      index,
      role: message.role ?? null,
      blockTypes: Array.isArray(message.content)
        ? message.content.map(block => block.type ?? null)
        : [typeof message.content],
      hasToolCalls: Array.isArray(message.tool_calls),
      hasToolCallId: Object.hasOwn(message, "tool_call_id")
    })),
    inputTypes: Array.isArray(body.input)
      ? body.input.map(item => item.type ?? "message")
      : []
  };
}

const example = {
  model: "YOUR_MODEL_ID",
  messages: [
    { role: "system", content: "비공개 애플리케이션 지시" },
    { role: "user", content: "비공개 사용자 입력" }
  ]
};
console.log(JSON.stringify(describeRequest(example), null, 2));

이 결과에서 처음에는 없던 역할이 확인되면 해당 역할을 추가한 변환 단계를 수정합니다. 본문에 system 문자열이 있는지만 검색하거나 모든 역할을 일괄 치환하면 원인을 놓칩니다.

Anthropic Messages: 처음 지시는 배열 밖으로 옮기기

Anthropic의 /v1/messages에 대화 시작 지시를 보내려면 messages[0]에 role: "system"을 넣는 대신 요청 본문의 최상위 system을 사용합니다. 사용자와 모델의 대화는 messages에 남겨 둡니다. 공식 Messages 사용 안내

다음은 처음부터 적용할 지시 하나와 사용자 질문 하나를 보내는 요청 본문입니다. YOUR_SUPPORTED_MODEL_ID를 해당 경로에서 지원하는 실제 ID로 바꾸고, 기존 인증과 API 버전 헤더를 유지합니다.

{
  "model": "YOUR_SUPPORTED_MODEL_ID",
  "max_tokens": 256,
  "system": "고객 문의를 분류합니다. 한국어로 답하고 인증 정보는 출력하지 않습니다.",
  "messages": [
    {
      "role": "user",
      "content": "system 역할을 지원하지 않는다는 400 오류가 발생했습니다."
    }
  ]
}

수정 전 첫 메시지에 있던 동일한 지시 텍스트를 system으로 옮기는 것이 핵심입니다. 사용자 질문과 기존의 정상적인 user·assistant 대화까지 합쳐 하나의 문자열로 만들지 않습니다. OpenAI의 developer나 instructions를 이 본문에 넣는 것도 Anthropic 형식으로 변환한 것이 아닙니다.

어댑터를 고칠 때는 시작 지시, 대화 기록, 도구 블록을 각각 다뤄야 합니다. 시작 지시를 messages로 주입하는 매핑은 최상위 system으로 수정하되, 대화 도중 들어온 지시까지 같은 규칙으로 이동시키지 않습니다. 뒤늦게 적용할 규칙을 처음 지시로 옮기면 적용 시점과 이전 대화의 의미가 바뀝니다.

대화 중간의 system은 언제 허용되나요?

현재 Anthropic 공식 안내는 Claude Fable 5.1·5, Mythos 5.1·5, Opus 5.5·4.8·5, Sonnet 5.5에서 대화 중간의 system 메시지를 지원한다고 명시합니다. Sonnet 5는 지원 목록에 포함되지 않습니다. 안내의 대상은 Claude API, Amazon Bedrock, Google Cloud이며, 모든 호환 게이트웨이가 같은 기능을 구현했다는 뜻은 아닙니다. 일반적인 텍스트 중간 지시에는 별도 베타 헤더가 필요하지 않습니다. 지원 모델과 메시지 위치

허용되는 위치도 정해져 있습니다.

• user 메시지 바로 뒤에 넣습니다. tool_result를 담은 user 메시지도 여기에 해당합니다.
• 서버 도구 결과로 끝나는 assistant 메시지 뒤에도 넣을 수 있습니다.
• 중간 지시 다음에는 assistant가 오거나, 중간 지시가 배열의 마지막에 있어야 합니다.
• 배열 첫 항목으로 넣거나, assistant의 tool_use와 그에 대한 user의 도구 결과 사이에 끼우면 안 됩니다. 연속된 system 메시지는 묶음 전체의 앞뒤 위치를 확인합니다.

다음 본문은 이 기능을 지원하는 모델과 경로에서 새 규칙을 다음 답변부터 적용하는 구조입니다. 처음부터 적용한 지시는 최상위에 유지하고, 나중에 추가한 운영 지시는 그 시점에 남깁니다.

{
  "model": "YOUR_MID_CONVERSATION_SUPPORTED_MODEL_ID",
  "max_tokens": 256,
  "system": "고객 문의를 분류하고 인증 정보는 출력하지 않습니다.",
  "messages": [
    { "role": "user", "content": "오류 코드가 400입니다." },
    { "role": "assistant", "content": "오류 원문과 요청 형식을 확인해 주세요." },
    { "role": "user", "content": "역할 오류였습니다. 수정 후 확인 항목도 알려 주세요." },
    { "role": "system", "content": "이후 답변은 한국어로 작성합니다." }
  ]
}

중간 system은 애플리케이션 운영자가 추가하는 지시입니다. 웹 검색 결과나 고객 메시지, 도구가 반환한 문자열을 높은 우선순위의 지시로 승격시키는 용도로 사용하지 않습니다. 같은 우선순위의 지시가 충돌하면 나중 지시는 이후 턴에 적용되므로, 단순히 모든 지시를 맨 앞으로 모으는 변환은 의미를 보존하지 못합니다. 중간 지시의 우선순위와 적용 범위

공식 API reference에는 아직 “입력에 system 역할이 없다”는 설명과 system을 포함한 역할 열거값이 함께 보입니다. 이 충돌 때문에 첫 지시는 최상위에 둔다는 규칙과, 특정 모델의 중간 지시 지원을 구분해야 합니다. 중간 지시는 구체적인 모델·위치를 설명하는 현재 기능 안내를 기준으로 판단합니다. SDK의 타입 정의가 예전 user·assistant만 허용한다면 서버 지원과 별도로 어댑터가 이 형식을 전달할 수 있는지도 확인합니다. Messages API reference

OpenAI와 Azure: 지원되는 지시 필드를 선택하기

OpenAI Chat Completions의 /v1/chat/completions는 messages 배열을 사용합니다. 공식 reference는 system과 developer를 설명하며, o1 이후 모델의 개발자 지시에는 developer를 사용하도록 안내합니다. 다만 실제 모델과 경로가 이 형식을 지원해야 합니다. “OpenAI 호환”이라는 표시만으로 다른 공급자의 역할 지원을 확정할 수 없습니다. Chat Completions 메시지 역할

developer를 지원하는 Chat 경로에서 처음 지시를 옮기는 예시는 다음과 같습니다. 원래 지시의 내용은 유지하고 사용자의 작업은 별도 메시지로 둡니다.

{
  "model": "YOUR_CHAT_MODEL_ID",
  "messages": [
    { "role": "developer", "content": "한국어로 문의를 분류하고 인증 정보는 출력하지 않습니다." },
    { "role": "user", "content": "이 API 오류의 확인 순서를 알려 주세요." }
  ]
}

developer가 거부된다면 이 치환을 되돌리기 전에 실제 모델, 엔드포인트, API 버전과 어댑터가 선언한 지원 범위를 확인합니다. 해당 경로가 system만 지원한다면 시작 지시는 그 역할로 유지합니다. user·assistant만 받는 게이트웨이라면 별도의 시스템 지시 필드나 올바른 변환 설정이 있는지 확인합니다. 높은 우선순위 지시를 전달할 방법이 없다면, 그 경로에서 원래 의미를 보존한 복구는 완료되지 않은 것입니다.

Responses에서는 매 요청에 필요한 instructions를 다시 전달하기

Responses의 /v1/responses에서는 최상위 instructions로 지시를 전달하고, 사용자 작업은 input에 넣을 수 있습니다. previous_response_id로 대화를 이어도 이전 응답의 instructions는 다음 요청에 자동으로 이어지지 않습니다. 계속 적용할 지시는 이번 요청에도 전달합니다. 공식 지시 적용 안내

다음은 이미 받은 응답을 이어가는 요청 본문입니다. resp_PREVIOUS_RESPONSE_ID는 실제 이전 응답 ID로 바꿔야 합니다.

{
  "model": "YOUR_RESPONSES_MODEL_ID",
  "previous_response_id": "resp_PREVIOUS_RESPONSE_ID",
  "instructions": "한국어로 문의를 분류하고 인증 정보는 출력하지 않습니다.",
  "input": "수정한 요청에서 도구 호출까지 어떻게 확인하나요?"
}

Chat 본문의 messages를 그대로 붙이거나 필드 이름만 input으로 바꾸면 모든 변환이 끝나는 것은 아닙니다. Responses는 메시지뿐 아니라 함수 호출과 결과 등 서로 다른 종류의 항목을 사용합니다. 아래 도구 결과 형식도 함께 맞춰야 합니다. Messages에서 Items로 변환하는 방법

Azure의 system 지원을 구형 규칙으로 판단하지 않기

Azure의 현재 reasoning 안내는 developer 또는 system을 사용하며, 최신 reasoning 모델은 기존 system 사용 방식에서의 이전을 지원한다고 설명합니다. 이 안내에서는 동일 요청에 system과 developer를 함께 쓰지 않도록 합니다. 따라서 Azure라는 이유로 system을 무조건 developer로 바꾸거나, 두 지시를 중복해 넣는 방식은 맞지 않습니다. Azure reasoning 모델의 지시 지원

현재 v1 경로와 기존 버전 경로도 구분합니다. 실제 배포 이름, 모델 버전, API 경로를 고정한 상태에서 그 조합의 문서를 확인하세요. “구형 Azure는 모두 developer를 지원하지 않는다”처럼 하나의 규칙으로 묶을 수는 없습니다.

tool 오류는 역할 이름과 호출 ID를 함께 고치기

tool이나 예전 function 역할이 거부될 때는 도구 호출과 결과를 연결하는 형식을 확인합니다. 결과만 user로 바꾸면 API가 받아들일 수 있어도 모델은 어느 호출의 결과인지 알 수 없게 됩니다.

OpenAI의 형식은 Chat reference와 Responses 전환 안내, Anthropic의 형식과 순서는 도구 호출 처리 안내를 기준으로 합니다.

아래는 이미 반환된 호출에 결과를 연결하는 JSON 조각입니다. 도구 정의, 전체 요청 본문, 실제 호출 ID는 생략했으므로 그대로 보내는 완성 요청이 아닙니다.

Chat에서는 모델이 준 호출을 보존하고 그 뒤에 같은 ID의 결과 메시지를 붙입니다.

[
  {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_EXAMPLE",
        "type": "function",
        "function": { "name": "lookup_status", "arguments": "{\"request_id\":\"demo\"}" }
      }
    ]
  },
  { "role": "tool", "tool_call_id": "call_EXAMPLE", "content": "{\"status\":\"complete\"}" }
]

Responses에서는 호출 결과가 메시지 역할이 아니라 항목입니다. 앞서 받은 호출의 call_id를 그대로 사용합니다.

{
  "type": "function_call_output",
  "call_id": "call_EXAMPLE",
  "output": "{\"status\":\"complete\"}"
}

이 항목을 다음 요청의 input 배열에 넣습니다. previous_response_id를 사용한다면 그 ID가 해당 함수 호출을 포함한 응답을 가리켜야 하며, 계속 필요한 instructions도 다시 보냅니다. 응답 항목을 직접 이어 붙이는 방식이라면 함수 호출과 필요한 reasoning 항목을 포함한 이전 응답을 보존합니다.

Anthropic에서는 도구 결과를 바로 다음 user 메시지 안에 둡니다.

[
  {
    "role": "assistant",
    "content": [
      { "type": "tool_use", "id": "toolu_EXAMPLE", "name": "lookup_status", "input": { "request_id": "demo" } }
    ]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_EXAMPLE", "content": "{\"status\":\"complete\"}" }
    ]
  }
]

한 응답에 여러 도구 호출이 있으면 각 호출에 맞는 결과를 모두 연결합니다. Anthropic의 결과 블록은 해당 사용자 메시지에서 일반 텍스트보다 먼저 와야 하며, tool_use와 tool_result 사이에 중간 system을 넣지 않습니다. 서버 도구 처리가 끝나지 않은 응답을 이어갈 때는 공식 안내의 별도 결과 전송 조건도 적용됩니다. 도구 결과의 배치와 연결 규칙

예전 role: "function" 형식을 최신 tool로 바꾸는 작업도 문자열 치환으로 끝나지 않습니다. 호출의 표현과 name·ID 연결을 함께 변환해야 합니다. 정상적인 도구·추론 기록을 삭제하거나 thinking·signature 블록을 다시 작성해 400을 피하는 방식은 이후 대화를 손상시킬 수 있습니다. 필요한 경우 전체 기록을 보존하는 해당 API용 어댑터를 사용합니다. Responses 항목 구조, Anthropic 대화 기록 보존 조건

Claude Code나 프레임워크를 거치면 변환 지점까지 확인하기

같은 역할 오류라도 클라이언트 버전 변경 뒤에 나타난 문제와 서버가 역할을 지원하지 않는 문제를 구분해야 합니다. 2026년 5월의 Claude Code 이슈 보고에는 운영체제, 클라이언트 버전과 공급자에 따른 실패 사례가 있습니다. 개별 사용자의 업그레이드·롤백 결과는 당시 조합의 관찰이며, 모든 환경에서 통하는 현재 해결 버전을 입증하지 않습니다.

현재 Claude Code 오류 문서는 중간 system의 위치 오류와 특정 텍스트를 한 번 user로 바꿔 재시도하는 클라이언트 처리를 설명합니다. 이 처리는 대화 중간 알림에 관한 특정 분기이며, 최초 시스템 지시나 모든 기록을 user로 바꾸라는 안내가 아닙니다. claude_code_version_too_old 또한 별도 오류이므로 실제 실행한 바이너리와 모델이 요구하는 최소 버전을 확인해야 합니다. Claude Code 오류별 안내

프레임워크를 사용하는 경우에는 변환 전후를 다음 순서로 비교합니다.

1. 애플리케이션이 전달한 지시와 대화 기록을 확인합니다.
2. 프레임워크가 추가한 기본 지시, 메모리, 도구 정책을 확인합니다.
3. 어댑터가 최종 필드와 역할로 바꾼 결과를 확인합니다.
4. 게이트웨이가 다른 API 형식으로 바꾼다면 그 전후의 역할·블록 종류도 확인합니다.

잘못된 단계 하나를 수정한 뒤 같은 실행 경로로 다시 확인합니다. 프레임워크를 빼고 직접 API에 보낸 요청만 성공했다면, 서버가 그 형식을 받는다는 단서는 얻었지만 프레임워크의 변환 문제가 해결된 것은 아닙니다. 인증 방식과 공급자 선택 자체가 불분명하다면 먼저 Claude Code API 설정 확인 순서에서 현재 연결을 확인합니다.

오류가 사라진 뒤 지시와 전체 작업까지 검증하기

원인을 좁힐 때는 공급자, 호스트·경로, API 버전, 모델·배포 이름, 클라이언트·어댑터를 고정하고 문제가 된 필드나 위치 하나만 바꿉니다. 모델과 공급자를 동시에 바꾸면 어느 수정이 효과가 있었는지 알기 어렵습니다. 동일한 잘못된 역할을 그대로 재전송해도 결정적인 구조 오류는 해결되지 않습니다.

최소 요청에서도 처음 문제가 된 기능을 유지합니다. 시스템 지시 오류라면 지시를 포함해야 하고, 도구 결과 오류라면 호출과 결과의 연결을 포함해야 합니다. user 한 줄만 보내는 테스트는 기본 요청이 되는지 확인할 뿐, 시스템 지시나 도구 기능을 복구했다고 증명하지 못합니다.

예를 들어 애플리케이션 지시가 “항상 한국어 JSON으로 분류”라면 합성 사용자 입력에 “영어 일반 문장으로 답해 달라”를 넣어 출력 언어와 JSON 파싱을 확인할 수 있습니다. 대화 중간 규칙은 추가한 다음 턴부터 적용되는지 확인합니다. 실제 고객 데이터나 비밀 대신 테스트용 내용을 사용하며, 한 번 통과한 결과를 모든 상황의 보장으로 해석하지 않습니다.

400이 401, 404나 다른 필드 오류로 바뀌었다면 새로운 실패 지점이 드러난 것입니다. 원래 역할 오류의 변화는 진단에 도움이 되지만 요청 성공을 뜻하지 않습니다. 2xx여도 빈 결과, 기대와 다른 구조, 끊긴 도구 처리라면 원래 작업은 완료되지 않았습니다.

같은 경로의 최소 요청에서 계속 실패하면 요청 ID, 정확한 모델·버전·경로, 변환 단계, 민감정보를 뺀 구조와 오류 본문을 묶어 담당자가 확인할 수 있게 준비합니다. 원문 프롬프트나 인증 정보까지 공유할 필요는 없습니다.

자주 묻는 질문

API 키나 잔액 문제일 수도 있나요?

system 등 특정 역할을 거부했다는 오류는 메시지 형식을 먼저 확인할 근거입니다. 다만 그 응답만으로 키의 유효성이나 잔액을 확정할 수는 없습니다. 전체 오류가 인증·할당량 오류인지, 역할 오류인지 구분하고 해당 항목만 수정합니다.

시스템 지시를 user로 옮기면 해결되나요?

서버가 받는 형식은 될 수 있어도 지시 우선순위는 달라집니다. Anthropic의 처음 지시는 최상위 system, OpenAI는 지원되는 system·developer 또는 Responses의 instructions에 둡니다. 그 지시 위치를 지원하지 않는 게이트웨이라면 원래 의미를 유지할 수 있는 변환 기능이 필요합니다. Anthropic Messages, OpenAI 지시 적용

Anthropic messages에는 system을 절대 넣을 수 없나요?

처음 지시는 최상위 system에 둡니다. 대화 중간 system은 현재 안내에 명시된 지원 모델과 위치에서 사용할 수 있습니다. SDK나 게이트웨이가 이를 전달하는지도 별도로 확인합니다. 중간 system의 지원 조건

Responses에서 이전 응답 ID만 보내면 지시도 유지되나요?

아닙니다. previous_response_id를 사용해도 이전 요청의 instructions는 이어지지 않으므로 계속 필요한 지시를 이번 요청에 다시 넣습니다. Responses 지시의 적용 범위

이미지나 artifact 관련 400도 같은 방법으로 고치나요?

아닙니다. 이미지 수·크기, 함수 artifact의 스키마, 공급자 자동 선택 실패는 각각 오류가 지목한 항목을 확인해야 합니다. 같은 400이라는 이유로 시스템 지시를 바꾸지 않습니다. Gemini에서 마지막 model 턴을 거부하는 경우도 해당 모델의 종료 턴 조건을 확인해야 하며, 정상적인 과거 model 기록을 모두 user로 바꾸는 해결법은 아닙니다. 현재 Gemini 모델의 마지막 턴 조건