> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 프록시 오류

> 인증, entity, 라우팅, 공급자, 업스트림 관련 장애를 진단합니다.

프록시에서 생성된 오류는 다음과 같은 형식입니다.

```json theme={"system"}
{
  "error": {
    "message": "No task 'ticket-classifier' in entity 'personal-user'. Did you mean to pass metadata[\"wandb.entity\"]?",
    "type": "proxy_error"
  }
}
```

모든 응답에는 `x-proxy-request-id`가 포함됩니다. 문제를 보고할 때 이 값을 함께 전달하세요.

<h2 id="common-failures">
  일반적인 실패 원인
</h2>

| 상태 | 일반적인 원인 | 조치 |
| - | - | - |
| 400 | 모델 누락, 잘못된 메타데이터, 안전하지 않은 트레이스 대상, 잘못된 형식의 JSON, 유효하지 않거나 충돌하는 `wandb-cache-mode` 값, 또는 스트리밍 호출에 대한 캐시 요청 | 요청 본문을 수정하거나 캐시 헤더를 제거하세요 |
| 401 | W\&B bearer 키가 누락되었거나 유효하지 않음 | 현재 유효한 W\&B API 키를 사용하세요 |
| 403 | 해당 키로 요청한 entity에 액세스할 수 없음 | `wandb.entity`를 변경하거나 팀 액세스 권한을 부여하세요 |
| 404 | 알 수 없는 프로젝트/버전/공급자 또는 지원되지 않는 경로 | entity, 프록시 모델 이름, 버전, 공급자 배포를 확인하세요 |
| 502 | 공급자에 연결할 수 없거나 공급자의 응답 스트림이 실패함 | 공급자 가용성과 자격 증명을 확인하세요 |
| 공급자 상태 | 선택한 공급자가 오류를 반환함 | 공급자 응답을 확인하세요. 프록시는 업스트림의 상태 코드와 본문을 그대로 전달합니다 |

<h2 id="the-most-common-entity-mistake">
  가장 흔한 entity 관련 실수
</h2>

개인 W\&B 키는 기본적으로 개인 entity를 사용합니다. 따라서 팀 프로젝트를 사용하려면 다음이 필요합니다.

```json theme={"system"}
{"metadata": {"wandb.entity": "team-name"}}
```

<h2 id="a-model-id-error-is-not-a-proxy-404">
  모델 ID 오류는 프록시 404가 아닙니다
</h2>

프록시는 공급자 이름만 검증할 뿐, 업스트림 모델 ID를 모두 검증하지는 않습니다. 공급자는 있지만 모델이 없으면 선택한 공급자가 자체 오류를 반환합니다. 이 차이를 알면 라우팅 설정 문제와 공급자 카탈로그 불일치 문제를 구분할 수 있습니다.

<h2 id="tracing-failures">
  트레이싱 실패
</h2>

트레이스 쓰기는 비동기로 수행되므로, 공급자 응답이 성공했다면 트레이스 쓰기가 실패하더라도 클라이언트에 실패가 반환되지 않습니다. 운영자는 동일한 프록시 요청 ID로 구조화된 쓰기 실패 이벤트를 모니터링합니다. 결정적(deterministic) 트레이스 입력 문제는 가능한 한 공급자로 요청을 전달하기 전에 거부됩니다.

<Accordion title="API: 실패 진단하기">
  에이전트에 요청 URL, 민감 정보를 가린 요청 본문, HTTP 상태, 전체 응답 본문, `x-proxy-request-id`를 제공하세요. bearer 키나 공급자 자격 증명은 공유하지 마세요.

  에이전트는 다음 순서로 확인해야 합니다.

  1. `metadata["wandb.entity"]`에 지정된 entity
  2. `model`이 프록시 모델 이름인지, 고정된 프로젝트 버전인지, 등록된 공급자 레퍼런스인지 여부
  3. 공급자와 라우팅 배포가 적용되었는지 여부
  4. 응답 본문이 프록시에서 반환되었는지, 업스트림 공급자에서 반환되었는지 여부

  기계 판독 가능한 오류 스키마는 [Inference proxy OpenAPI 사양](/ko/openapi/model-distillation/proxy.openapi.yaml)에서 확인할 수 있습니다.
</Accordion>


## Related topics

- [모델 라우팅](/ko/model-distillation/proxy/model-routing.md)