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

> role 미지원 오류는 실제 API가 받는 필드와 메시지 위치부터 맞춰야 합니다. Claude의 처음 지시는 최상위 system에, OpenAI의 지시는 해당 API가 지원하는 위치에 둡니다. 도구 호출 ID와 대화 기록을 보존한 뒤 지시 준수와 전체 작업까지 확인하세요.

- URL: https://blog.laozhang.ai/ko/posts/api-400-role-system-is-not-supported-on-this-model
- Published: 2026-05-21
- Updated: 2026-11-10
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ko/about)
- Topic: 문제 해결
- Tags: API 400, OpenAI API, Claude API, 시스템 프롬프트, 도구 호출

---
`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 형식으로 변환하는 경우에는 변환 전 배열만 보고 판단할 수 없습니다.

| 확인할 항목 | 구체적으로 기록할 값 | 수정 방향을 가르는 이유 |
| --- | --- | --- |
| 요청 주소 | 호스트와 실제 경로, 예: `/v1/messages` | 같은 모델 이름이어도 메시지 형식이 다를 수 있습니다. |
| 모델과 API 버전 | 실제 모델 ID·배포 이름, 사용 중인 버전 | 역할과 새 기능 지원 범위가 달라집니다. |
| 메시지 위치 | 인덱스, 역할, 콘텐츠 블록 종류 | 첫 지시인지, 중간 지시인지, 도구 결과인지 구분합니다. |
| 변환 단계 | 클라이언트·SDK·프레임워크·어댑터 버전 | 어디서 역할이나 필드가 추가됐는지 찾습니다. |
| 응답 | 상태 코드, 오류 원문, 있는 경우 `param`·요청 ID | 클라이언트 검사 실패와 서버 거부를 구분합니다. |

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

```javascript
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` 문자열이 있는지만 검색하거나 모든 역할을 일괄 치환하면 원인을 놓칩니다.

![앱부터 어댑터와 최종 요청까지 역할이 바뀐 위치를 확인하는 흐름](https://blog.laozhang.ai/posts/ko/api-400-role-system-is-not-supported-on-this-model/img/request-transformation-check.webp)

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

Anthropic의 `/v1/messages`에 대화 시작 지시를 보내려면 `messages[0]`에 `role: "system"`을 넣는 대신 요청 본문의 최상위 `system`을 사용합니다. 사용자와 모델의 대화는 `messages`에 남겨 둡니다. [공식 Messages 사용 안내](https://platform.claude.com/docs/es/build-with-claude/working-with-messages)

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

```json
{
  "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` 메시지를 지원한다고 명시합니다. 2026년 11월 10일 다시 확인한 같은 안내의 지원 목록에는 11월 9일 출시된 Fable 5.2와 Mythos 5.2도 포함되어 있으며, 목록 맨 앞에 올라 있습니다. Sonnet 5는 지원 목록에 포함되지 않습니다. 안내의 대상은 Claude API, Amazon Bedrock, Google Cloud이며, 모든 호환 게이트웨이가 같은 기능을 구현했다는 뜻은 아닙니다. 일반적인 텍스트 중간 지시에는 별도 베타 헤더가 필요하지 않습니다. [지원 모델과 메시지 위치](https://platform.claude.com/docs/es/build-with-claude/mid-conversation-system-messages)

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

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

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

```json
{
  "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`은 애플리케이션 운영자가 추가하는 지시입니다. 웹 검색 결과나 고객 메시지, 도구가 반환한 문자열을 높은 우선순위의 지시로 승격시키는 용도로 사용하지 않습니다. 같은 우선순위의 지시가 충돌하면 나중 지시는 이후 턴에 적용되므로, 단순히 모든 지시를 맨 앞으로 모으는 변환은 의미를 보존하지 못합니다. [중간 지시의 우선순위와 적용 범위](https://platform.claude.com/docs/es/build-with-claude/mid-conversation-system-messages)

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

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

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

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

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

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

![Chat 메시지와 Responses instructions 위치 및 이어지는 요청의 지시 재전달을 비교한 그림](https://blog.laozhang.ai/posts/ko/api-400-role-system-is-not-supported-on-this-model/img/chat-responses-instruction-fields.webp)

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

Responses의 `/v1/responses`에서는 최상위 `instructions`로 지시를 전달하고, 사용자 작업은 `input`에 넣을 수 있습니다. **`previous_response_id`로 대화를 이어도 이전 응답의 `instructions`는 다음 요청에 자동으로 이어지지 않습니다.** 계속 적용할 지시는 이번 요청에도 전달합니다. [공식 지시 적용 안내](https://developers.openai.com/api/docs/guides/text#message-roles-and-instruction-following)

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

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

Chat 본문의 `messages`를 그대로 붙이거나 필드 이름만 `input`으로 바꾸면 모든 변환이 끝나는 것은 아닙니다. Responses는 메시지뿐 아니라 함수 호출과 결과 등 서로 다른 종류의 항목을 사용합니다. 아래 도구 결과 형식도 함께 맞춰야 합니다. [Messages에서 Items로 변환하는 방법](https://developers.openai.com/api/docs/guides/migrate-to-responses#2-map-messages-to-items)

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

Azure의 현재 reasoning 안내는 `developer` 또는 `system`을 사용하며, 최신 reasoning 모델은 기존 `system` 사용 방식에서의 이전을 지원한다고 설명합니다. 이 안내에서는 **동일 요청에 `system`과 `developer`를 함께 쓰지 않도록** 합니다. 따라서 Azure라는 이유로 `system`을 무조건 `developer`로 바꾸거나, 두 지시를 중복해 넣는 방식은 맞지 않습니다. [Azure reasoning 모델의 지시 지원](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/reasoning)

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

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

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

| API | 도구 호출을 반환하는 형식 | 결과를 돌려주는 형식 | 연결하는 ID |
| --- | --- | --- | --- |
| OpenAI Chat Completions | `assistant.tool_calls` | `role: "tool"` 메시지 | `tool_call_id` ↔ 호출의 `id` |
| OpenAI Responses | `type: "function_call"` 항목 | `type: "function_call_output"` 항목 | `call_id` |
| Anthropic Messages | `assistant` 콘텐츠의 `tool_use` 블록 | 다음 `user` 콘텐츠의 `tool_result` 블록 | `tool_use_id` ↔ 호출의 `id` |

OpenAI의 형식은 [Chat reference](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)와 [Responses 전환 안내](https://developers.openai.com/api/docs/guides/migrate-to-responses#2-map-messages-to-items), Anthropic의 형식과 순서는 [도구 호출 처리 안내](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls)를 기준으로 합니다.

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

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

```json
[
  {
    "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`를 그대로 사용합니다.

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

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

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

```json
[
  {
    "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`을 넣지 않습니다. 서버 도구 처리가 끝나지 않은 응답을 이어갈 때는 공식 안내의 별도 결과 전송 조건도 적용됩니다. [도구 결과의 배치와 연결 규칙](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls)

예전 `role: "function"` 형식을 최신 `tool`로 바꾸는 작업도 문자열 치환으로 끝나지 않습니다. 호출의 표현과 `name`·ID 연결을 함께 변환해야 합니다. 정상적인 도구·추론 기록을 삭제하거나 thinking·signature 블록을 다시 작성해 400을 피하는 방식은 이후 대화를 손상시킬 수 있습니다. 필요한 경우 전체 기록을 보존하는 해당 API용 어댑터를 사용합니다. [Responses 항목 구조](https://developers.openai.com/api/docs/guides/migrate-to-responses#2-map-messages-to-items), [Anthropic 대화 기록 보존 조건](https://platform.claude.com/docs/es/build-with-claude/mid-conversation-system-messages)

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

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

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

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

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

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

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

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

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

| 확인 단계 | 확인할 결과 | 아직 확인되지 않은 것 |
| --- | --- | --- |
| 요청 구조 | 같은 경로에서 역할·위치 오류가 사라짐 | 지시 준수와 도구 실행 |
| 지시 우선순위 | 합성 사용자 입력이 지시와 충돌해도 필요한 애플리케이션 규칙을 유지 | 모든 입력에서의 동작 보장 |
| 도구 연결 | 호출 ID에 맞는 결과가 모델에 돌아가고 최종 답변까지 이어짐 | 전체 앱의 출력·파일 처리 |
| 실제 작업 | 원래 프레임워크에서 요구한 형식과 결과를 얻음 | 다른 모델·버전·공급자에서의 동작 |

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

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

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

## 자주 묻는 질문

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

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

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

서버가 받는 형식은 될 수 있어도 지시 우선순위는 달라집니다. Anthropic의 처음 지시는 최상위 `system`, OpenAI는 지원되는 `system`·`developer` 또는 Responses의 `instructions`에 둡니다. 그 지시 위치를 지원하지 않는 게이트웨이라면 원래 의미를 유지할 수 있는 변환 기능이 필요합니다. [Anthropic Messages](https://platform.claude.com/docs/es/build-with-claude/working-with-messages), [OpenAI 지시 적용](https://developers.openai.com/api/docs/guides/text#message-roles-and-instruction-following)

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

처음 지시는 최상위 `system`에 둡니다. 대화 중간 `system`은 현재 안내에 명시된 지원 모델과 위치에서 사용할 수 있습니다. SDK나 게이트웨이가 이를 전달하는지도 별도로 확인합니다. [중간 system의 지원 조건](https://platform.claude.com/docs/es/build-with-claude/mid-conversation-system-messages)

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

아닙니다. `previous_response_id`를 사용해도 이전 요청의 `instructions`는 이어지지 않으므로 계속 필요한 지시를 이번 요청에 다시 넣습니다. [Responses 지시의 적용 범위](https://developers.openai.com/api/docs/guides/text#message-roles-and-instruction-following)

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

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

## 참고 자료

이 글이 링크한 외부 페이지를 본문에 나온 순서대로 정리했습니다. 마지막 업데이트: 2026-11-10.

- [공식 Messages 사용 안내](https://platform.claude.com/docs/es/build-with-claude/working-with-messages) (platform.claude.com)
- [지원 모델과 메시지 위치](https://platform.claude.com/docs/es/build-with-claude/mid-conversation-system-messages) (platform.claude.com)
- [Messages API reference](https://platform.claude.com/docs/en/api/messages/create) (platform.claude.com)
- [Chat Completions 메시지 역할](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create) (developers.openai.com)
- [공식 지시 적용 안내](https://developers.openai.com/api/docs/guides/text) (developers.openai.com)
- [Messages에서 Items로 변환하는 방법](https://developers.openai.com/api/docs/guides/migrate-to-responses) (developers.openai.com)
- [Azure reasoning 모델의 지시 지원](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/reasoning) (learn.microsoft.com)
- [도구 호출 처리 안내](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls) (platform.claude.com)
- [Claude Code 이슈 보고](https://github.com/anthropics/claude-code/issues/61412) (github.com)
- [Claude Code 오류별 안내](https://code.claude.com/docs/ru/errors) (code.claude.com)
- [현재 Gemini 모델의 마지막 턴 조건](https://ai.google.dev/gemini-api/docs/generate-content/latest-model) (ai.google.dev)
