AI API 문제 해결
이 페이지에서는 LLMPool AI API의 주요 오류, 원인과 해결 방법을 설명합니다. 먼저 올바른 프로토콜을 사용하고 있는지 확인하세요.
- OpenAI 호환 Base URL:
https://api.benpay.ai/openai/v1 - Anthropic 호환 Base URL:
https://api.benpay.ai/anthropic/v1
필드 설명은 오류 응답을 참고하세요. HTTP 상태로 큰 분류를 확인하고 OpenAI error.code 또는 Anthropic error.type으로 구체적인 처리를 결정합니다. message 문자열에 의존하지 마세요.
권장 조사 순서
- HTTP 상태, 요청 경로, 응답 Header의 요청 ID를 기록합니다. API 키나 전체 요청 본문은 기록하지 않습니다.
- 비
2xx응답도status: "failed"가 있는 Response 같은 유효한 비즈니스 객체인지 먼저 확인합니다. - OpenAI는 HTTP와
error.code, Anthropic은 HTTP와error.type으로 원인을 찾습니다. - 아래 표에 따라 요청 수정, 지원 문의 또는 제한된 재시도를 수행합니다.
인증 및 접근
OpenAI error.code | Anthropic error.type | HTTP | 자동 재시도 | 원인 | 해결 방법 |
|---|---|---|---|---|---|
invalid_api_key | authentication_error | 401 | 아니요 | API 키 누락, 형식 오류, 무효, 만료, 비활성화, 계정 미연결 또는 계정 사용 불가 | Header와 Base URL을 확인하고 Dashboard의 API 키에서 상태 확인 |
ip_not_allowed | authentication_error 및 error.code=ip_not_allowed | 403 | 아니요 | 요청 IP가 허용 목록에 없거나 프록시가 IP를 올바르게 전달하지 않음 | IP 허용 목록, 외부 IP, 리버스 프록시 설정 확인 |
OpenAI:
Authorization: Bearer YOUR_API_KEY
Anthropic은 다음 형식을 우선 사용합니다.
x-api-key: YOUR_API_KEY
Bearer Token도 사용할 수 있습니다. 둘 다 제공하면 x-api-key가 우선합니다.
잔액 및 과금
OpenAI error.code | Anthropic error.type | HTTP | 자동 재시도 | 원인 | 해결 방법 |
|---|---|---|---|---|---|
insufficient_wallets | invalid_request_error(별도 코드 없음) | 402 | 아니요 | 사용 가능한 지갑 및 예약 잔액 부족 | Dashboard에서 충전하거나 조직 관리자에게 문의 |
meter_price_rules_error | 해당 없음 | 400 또는 500 | 아니요 | 계량 규칙 누락, 불일치 또는 읽기 실패 | 다른 모델을 사용하거나 지원팀에 문의 |
요청 및 매개변수
OpenAI error.code | Anthropic error.type | HTTP | 자동 재시도 | 원인 | 해결 방법 |
|---|---|---|---|---|---|
invalid_request | invalid_request_error | 400 | 아니요 | JSON, Content-Type 또는 파싱 오류 | JSON, 필드 형식, 필수 필드 확인 |
invalid_request_error | invalid_request_error | 400 또는 422 | 아니요 | 업스트림이 매개변수 조합을 거부 | 모델이 지원하는 매개변수 확인 |
missing_model | invalid_request_error | 400 | 아니요 | model 누락 또는 빈 값 | 모델 페이지의 Product ID 사용 |
context_length_exceeded | invalid_request_error | 400 | 아니요 | 입력과 출력이 컨텍스트 제한 초과 | 기록, 첨부 파일, 최대 출력 Token 축소 |
conversion_error | 해당 없음 | 400 | 아니요 | Chat Completions 요청을 Responses로 변환할 수 없음 | 입력 단순화 및 미지원 필드 제거 |
request_too_large | request_too_large | 413 | 아니요 | HTTP 본문이 제한 초과 | 텍스트, 이미지 또는 파일 크기 축소 |
method_not_allowed | invalid_request_error | 405 | 아니요 | HTTP 메서드가 잘못됨 | API 문서의 메서드 사용 |
not_found | not_found_error | 404 | 아니요 | 경로나 리소스가 없음 | Base URL, 버전 경로, 리소스 ID 확인 |
모델 및 라우팅
OpenAI error.code | Anthropic error.type | HTTP | 자동 재시도 | 원인 | 해결 방법 |
|---|---|---|---|---|---|
invalid_model | invalid_request_error | 400 | 아니요 | 모델 ID가 비었거나 형식이 잘못됨 | 모델 페이지에서 Product ID 복사 |
model_not_found | not_found_error | 404 | 아니요 | Product를 찾을 수 없음 | 철자와 모델 공개 상태 확인 |
model_not_supported | invalid_request_error | 400 | 아니요 | 현재 프로토콜 또는 기능을 지원하지 않음 | 지원 모델 또는 API 선택 |
service_unavailable | overloaded_error | OpenAI 503 / Anthropic 529 | 예 | 사용 가능한 모델 또는 용량이 없음 | 백오프하거나 모델 변경 |
카탈로그에 모델이 표시되어도 현재 추론 용량이 보장되지는 않습니다.
속도 제한
OpenAI error.code | Anthropic error.type | HTTP | 자동 재시도 | 원인 | 해결 방법 |
|---|---|---|---|---|---|
rate_limit_exceeded | rate_limit_error | 429 | 예 | IP, API 키, 플랫폼 또는 업스트림 제한 | Retry-After를 따르고 동시 요청을 줄여 지수 백오프 |
rate_limited | rate_limit_error | 429 | 예 | 후보 업스트림이 모두 제한됨 | 백오프하거나 모델 변경 |
약 1s부터 시작해 지터를 더하고 간격을 두 배로 늘리며 최대 횟수와 전체 제한 시간을 설정하세요.
업스트림 서비스
OpenAI error.code | Anthropic error.type | HTTP | 자동 재시도 | 원인 | 해결 방법 |
|---|---|---|---|---|---|
upstream_configuration_error | api_error | OpenAI 502 / Anthropic 500 | 아니요 | 업스트림 인증, 모델 매핑 또는 플랫폼 구성 오류 | 지원팀에 문의 |
upstream_unavailable | api_error | 502 | 예 | 업스트림 연결 실패 또는 일시적 사용 불가 | 백오프하고 필요하면 모델 변경 |
upstream_timeout | api_error | 504 | 예 | 업스트림 응답 시간 초과 | 백오프하거나 컨텍스트 축소 |
| 해당 없음 | overloaded_error | 529 | 예 | Anthropic 호환 업스트림 과부하 | 백오프하거나 모델 변경 |
내부 오류
OpenAI error.code | Anthropic error.type | HTTP | 자동 재시도 | 원인 | 해결 방법 |
|---|---|---|---|---|---|
internal_error | api_error | 500 | 제한적 | DB, 매핑, 복호화 또는 기타 내부 처리 실패 | 소수 횟수만 재시도하고 계속되면 지원팀에 문의 |
file_service_error | 해당 없음 | 500 | 제한적 | 이미지 또는 첨부 파일 내부 처리 실패 | 형식과 크기를 확인한 뒤 재시도 |
response_conversion_error | 해당 없음 | 500 | 제한적 | 업스트림 응답을 Responses 객체로 변환할 수 없음 | 제한적으로 재시도하거나 모델 변경 |
스트림 중단
스트림이 시작된 뒤 HTTP 상태는 200인 상태로 stream_error 또는 Anthropic event: error를 받을 수 있습니다.
- 스트림을 즉시 끝내고 받은 조각을 완전한 결과로 처리하지 않습니다.
- 오류 형식과 로컬 요청 시간을 기록하고 API 키나 민감한 본문은 기록하지 않습니다.
- 안전하게 재시도할 수 있는지 확인한 뒤 백오프합니다.
- 계속 발생하면 모델을 변경하고 지원팀에 문의합니다.
이벤트 구조는 오류 응답을 참고하세요.
자주 발생하는 상황
401이 계속 반환됨
- Dashboard 주소가 아니라 LLMPool OpenAI 또는 Anthropic Base URL을 사용했는지 확인합니다.
- Admin Token이나 Tenant Access Token을 AI API 키로 사용하지 마세요.
- 키를 다시 복사하고 공백과 Header 형식을 확인합니다.
- Dashboard에서 만료 또는 비활성 상태를 확인합니다.
모델이 404를 반환함
- 모델 페이지에서 모델 이름을 복사합니다.
- 업스트림 fullname이 아니라 Product ID를 사용합니다.
- 프로토콜과 작업이 모델 기능에 맞는지 확인합니다.
429, 5xx 또는 529가 자주 발생함
- 동시 요청을 줄이고
Retry-After와 지터가 있는 백오프를 사용합니다. - 재시도 횟수를 제한하고 다른 모델도 사용해 봅니다.
- 시간, 프로토콜, 경로, HTTP 상태, 구조화된 오류, Product ID를 기록합니다.
- 여러 모델에서 계속되면 지원팀에 문의합니다.
지원 문의
발생 시간과 시간대, 프로토콜, 요청 경로와 메서드, HTTP 상태, 오류 형식과 코드, Product ID, 스트리밍 여부, 응답 Header의 요청 ID를 제공하세요.
전체 API 키, 요청 본문, GraphQL 문서와 변수, 파일 내용 또는 쿼리 문자열이 포함된 전체 URL은 제공하지 마세요.