프록시 오류

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

{
  "error": {
    "message": "No routing configuration for project 'your-team/ticket-classifier'",
    "type": "proxy_error"
  }
}

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

일반적인 실패 사례

상태	일반적인 원인	조치
`400`	메타데이터가 잘못되었거나 JSON 형식이 올바르지 않음	요청 본문을 수정하세요
`400`	`OpenAI-Project must be entity/project`: 헤더가 `[ENTITY]/[PROJECT]` 형식이 아닙니다. `OPENAI_PROJECT_ID`에 `proj_abc123`과 같은 OpenAI 프로젝트 ID가 남아 있는 경우가 많으며, 이때 오류 메시지에 해당 변수를 해제하거나 변경하라는 힌트가 포함됩니다	SDK의 `project` 옵션 또는 `OPENAI_PROJECT_ID`를 `[ENTITY]/[PROJECT]`로 설정하세요
`400`	`model`에 프로젝트 별칭 또는 `alias@vN`을 지정하고 `OpenAI-Project`도 함께 전송함	`model: "router"`를 전송하고 `metadata["forge.project_version"]`으로 버전을 선택하세요
`400`	`OpenAI-Project` 없이 `forge.project_version`을 전송했거나, 값이 양의 정수가 아님	헤더를 함께 전송하고, `"2"`와 같은 버전 값을 지정하세요
`400`	`Forge-Cache-Mode` 값이 잘못되었거나 스트리밍 호출에 캐시를 요청함	캐시 헤더를 수정하거나 제거하세요
`401`	Forge API 키가 없거나 유효하지 않음	유효한 API 키를 사용하세요
`403`	키에 `OpenAI-Project`의 entity에 대한 액세스 권한이 없습니다. 프록시는 프로젝트를 조회하기 전에 액세스 권한을 먼저 확인합니다	entity를 변경하거나 팀 액세스 권한을 부여하세요
`404`	`No routing configuration for project '[ENTITY]/[PROJECT]'`: 프로젝트 이름이 잘못되었거나(Weights & Biases 프로젝트 이름과 다른 프로젝트 별칭을 사용한 경우가 많음) 라우팅이 아직 게시되지 않았습니다	Studio에서 `OpenAI-Project` 값을 복사하고, 라우팅이 적용될 때까지 기다리세요
`404`	`Project '[ENTITY]/[PROJECT]' has no version N`: `forge.project_version`에 존재하지 않는 버전을 지정했습니다	해당 버전을 생성하거나 값을 수정하세요
`404`	`OpenAI-Project` 없이 `model: "router"`를 전송했습니다. 오류 메시지에 헤더를 전송하라는 안내가 포함됩니다	SDK의 `project` 옵션 또는 `OPENAI_PROJECT_ID`를 설정하세요
`404`	모델 재정의에 알 수 없는 공급자를 지정했거나 지원되지 않는 경로를 사용함	공급자 이름과 공급자 배포를 확인하세요
`502`	공급자에 연결할 수 없거나 공급자의 응답 스트림이 실패함	공급자 가용성과 사용자 인증 정보를 확인하세요
공급자 상태	선택한 공급자가 오류를 반환함	공급자 응답을 확인하세요. 프록시는 업스트림의 상태와 본문을 그대로 전달합니다

가장 흔한 프로젝트 관련 실수

OpenAI-Project에는 프로젝트 별칭이 아니라 해당 프로젝트의 Weights & Biases 프로젝트 이름을 지정해야 합니다. 프로젝트를 생성할 때 별칭과 다른 프로젝트 이름을 사용했다면 두 값이 서로 다릅니다. 이 경우 OpenAI-Project에 별칭을 지정하면 No routing configuration for project 메시지와 함께 404가 반환됩니다. Studio의 프로젝트 헤더에서 값을 복사하세요:

OpenAI-Project: your-team/ticket-classifier

모델 ID 오류는 프록시 `404`가 아닙니다

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

트레이싱 실패

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

API: 실패 진단하기

에이전트에 요청 URL, OpenAI-Project 헤더 값, 민감 정보를 가린 요청 본문, HTTP 상태, 전체 응답 본문, x-proxy-request-id를 제공하세요. bearer 키나 공급자 사용자 인증 정보는 공유하지 마세요.에이전트는 다음 항목을 순서대로 확인해야 합니다.

OpenAI-Project 값, 그리고 해당 프로젝트가 프로젝트 별칭이 아닌 Weights & Biases 프로젝트 이름인지 여부
model이 router인지 모델 재정의인지, 그리고 forge.project_version이 어떤 버전을 선택하는지
공급자와 라우팅 배포가 적용되었는지 여부
응답 본문이 프록시에서 반환되었는지, 업스트림 공급자에서 반환되었는지 여부

오류 응답 스키마는 Chat Completions API 참조에서 확인하세요.

Model Distillation

Serverless Training

일반적인 실패 사례

가장 흔한 프로젝트 관련 실수

모델 ID 오류는 프록시 `404`가 아닙니다

트레이싱 실패

​일반적인 실패 사례

​가장 흔한 프로젝트 관련 실수

​모델 ID 오류는 프록시 404가 아닙니다

​트레이싱 실패

일반적인 실패 사례

가장 흔한 프로젝트 관련 실수

모델 ID 오류는 프록시 `404`가 아닙니다

트레이싱 실패