AI API 오류 응답

LLMPool의 OpenAI 호환 API와 Anthropic 호환 API는 각 프로토콜에 맞는 오류 형식을 사용합니다. 애플리케이션은 먼저 HTTP 상태 코드를 확인한 다음 구조화된 오류 필드를 읽어야 합니다.

오류 메시지는 사람이 읽기 위한 것이며 안정적인 파싱 계약이 아닙니다. message 문자열을 비교하여 재시도나 처리 분기를 결정하지 마세요.

OpenAI 호환 형식

{
  "error": {
    "message": "The requested model was not found.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

필드	형식	설명
`error.message`	string	개발자가 읽을 수 있는 안전한 오류 설명
`error.type`	string	OpenAI 호환 오류 분류
`error.param`	string 또는 null	오류와 관련된 요청 필드
`error.code`	string 또는 null	프로그램에서 판단할 수 있는 세부 오류 코드

HTTP 상태 코드와 error.code를 우선 사용하세요.

Anthropic 호환 형식

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested model was not found."
  }
}

필드	형식	설명
`type`	string	항상 `error`
`error.type`	string	Anthropic 호환 오류 분류
`error.message`	string	개발자가 읽을 수 있는 안전한 설명
`error.code`	string 또는 생략	`ip_not_allowed` 등 일부 오류에서만 제공

Anthropic 클라이언트는 HTTP 상태와 error.type을 중심으로 처리해야 합니다.

필드 정의 주체

내용	주요 출처	클라이언트 처리 방식
HTTP 상태	LLMPool이 장애 분류에 따라 표준화하며 일부 전달 응답은 업스트림 값을 유지	아래 표에 따라 분류
OpenAI `error.code`	LLMPool이 정의한 일반 오류 코드	HTTP 상태와 함께 프로그램 판단에 사용 가능
OpenAI `error.type` / Anthropic `error.type`	LLMPool이 호환 형식으로 매핑하며 전달 응답은 업스트림에서 올 수 있음	문서에 명시된 값만 사용
`error.message`	안전한 표준 문구 또는 전달된 업스트림 문구	표시, 로그, 수동 조사에만 사용

비 2xx 비즈니스 응답 예외

일부 호환 업스트림은 구조가 올바른 비즈니스 응답에 비 2xx 상태를 붙입니다. LLMPool이 본문이 대상 엔드포인트와 일치한다고 확인하면 상태를 유지한 채 비즈니스 객체를 반환할 수 있습니다.

Chat Completions 및 Responses의 유효한 OpenAI 객체
Anthropic 비스트리밍 Messages, Files, Message Batches 객체
status: "failed"와 사용량을 포함하는 Responses 객체

클라이언트는 비 2xx 응답에서 오류 envelope를 읽기 전에 대상 엔드포인트의 비즈니스 객체인지 확인해야 합니다.

주요 HTTP 상태 코드

상태	의미	권장 처리
`400`	요청, 매개변수, 모델 기능 또는 컨텍스트 길이가 잘못됨	수정 후 다시 요청
`401`	API 키가 유효하지 않음	키와 인증 Header 확인, 자동 재시도 금지
`402`	계정 잔액 부족	충전 후 다시 요청
`403`	요청 IP가 허용되지 않음	IP 허용 목록 확인
`404`	모델, 응답 또는 리소스를 찾을 수 없음	ID와 경로 확인
`405`	HTTP 메서드 미지원	문서에 명시된 메서드 사용
`413`	요청 본문이 너무 큼	본문 또는 첨부 파일 축소
`422`	JSON은 유효하지만 매개변수 조합이 잘못됨	수정 후 다시 요청
`429`	플랫폼 또는 업스트림 속도 제한	`Retry-After`를 따르고 백오프
`500`	LLMPool 내부 오류. Anthropic에서는 업스트림 구성 오류일 수도 있음	구조화된 오류 형식으로 판단
`502`	업스트림 구성 오류 또는 사용 불가	`error.code`로 재시도 여부 판단
`503`	OpenAI 호환 모델 용량 없음	백오프 또는 모델 변경
`504`	업스트림 시간 초과	백오프하고 필요하면 입력 축소
`529`	Anthropic 호환 업스트림 또는 모델 과부하	백오프 또는 모델 변경

자세한 내용은 문제 해결을 참고하세요.

스트리밍 오류

HTTP 200과 응답 Header가 전송된 뒤 스트림이 실패할 수 있습니다. 클라이언트는 최초 HTTP 상태뿐 아니라 SSE 이벤트를 끝까지 파싱해야 합니다.

Chat Completions

{
  "error": {
    "message": "Upstream stream interrupted.",
    "type": "server_error",
    "param": null,
    "code": "stream_error"
  }
}

Responses API

{
  "type": "error",
  "code": "stream_error",
  "message": "Upstream stream interrupted.",
  "param": null,
  "sequence_number": 7
}

Responses API는 정상적인 response.failed 종료 이벤트를 반환할 수도 있습니다.

{
  "type": "response.failed",
  "sequence_number": 7,
  "response": {
    "id": "resp_123",
    "object": "response",
    "status": "failed",
    "error": {
      "code": "server_error",
      "message": "The response failed."
    }
  }
}

response.failed는 Responses 프로토콜의 비즈니스 종료 상태입니다. LLMPool은 이 이벤트를 전달하고 스트림을 끝내며 합성 오류를 추가하지 않습니다. type: "error"와 type: "response.failed"를 모두 처리해야 합니다.

Anthropic Messages

Anthropic Messages는 SSE event: error를 사용합니다.

{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "Upstream stream interrupted."
  }
}

스트림 오류나 실패 종료 상태를 받으면 스트림을 끝내고 이미 받은 조각을 완전한 응답으로 처리하지 마세요.

재시도 원칙

400, 401, 402, 403, 404, 405, 413, 422는 일반적으로 요청이나 계정 상태를 먼저 수정해야 합니다.
429 rate_limit_exceeded, 429 rate_limited, 502 upstream_unavailable, 503 service_unavailable, 504 upstream_timeout, 529 overloaded_error에는 지터가 포함된 지수 백오프를 사용할 수 있습니다.
502 upstream_configuration_error와 400/500 meter_price_rules_error는 플랫폼 구성 문제이므로 같은 요청을 반복해도 해결되지 않습니다.
500 internal_error 또는 Anthropic 500 api_error는 소수 횟수만 재시도하고 계속되면 지원팀에 문의하세요.
Retry-After Header를 우선 따르세요.
리소스 생성이나 Batch 같은 비멱등 작업은 첫 요청의 성공 여부를 확인한 뒤 재시도하세요.
최대 재시도 횟수와 전체 제한 시간을 설정하세요.

LLMPool은 표준 오류에 업스트림 원문 응답, 인증 정보, 내부 모델 이름, API Base 또는 프록시 주소를 포함하지 않습니다. 지원팀에 문의할 때도 전체 API 키, 요청 본문 또는 파일 내용을 보내지 마세요.