핵심 가이드
API 오류 처리
오류 코드를 읽고, 유용한 경우에만 재시도하며, Request ID를 보관하세요
HTTP 상태 코드와 code를 통해 오류를 처리하세요. message는 사람이 읽기 위한 용도이며 예고 없이 변경될 수 있습니다.
Chat Completions 및 Responses는 OpenAI 스타일의 error 객체를 사용합니다. Anthropic Messages와 Gemini는 각자의 오류 형식을 유지하므로, 모든 TokenLab API에 하나의 파서를 사용하지 마십시오.
{
"error": {
"message": "Human-readable description",
"type": "error_type",
"code": "error_code",
"param": "parameter_name",
"retryable": true,
"retry_after": 30
}
}TokenLab에서 생성된 OpenAI 호환 오류에는 항상 message와 type만 포함됩니다. 다른 필드는 관련이 있을 때만 나타납니다.
상태 코드
| 상태 | 의미 | 일반적인 조치 |
|---|---|---|
400 | 필드, 모델 ID 또는 입력이 유효하지 않음 | 요청을 수정하세요; 변경 없이 반복하지 마십시오 |
401 | API 키가 없거나, 유효하지 않거나, 만료되었거나, 취소됨 | 키를 교체하세요 |
402 | 잔액 또는 API 키 제한이 너무 낮음 | 충전하거나, 제한을 높이거나, 요청을 줄이세요 |
403 | 이 키는 해당 리소스나 모델을 사용할 수 없음 | 키의 권한이나 모델을 변경하세요 |
404 | 리소스가 존재하지 않거나 더 이상 사용할 수 없음 | ID와 이를 생성한 API 키를 확인하세요 |
413 | 요청 또는 업로드된 파일이 너무 큼 | 문서화된 모델 또는 엔드포인트 제한에 맞춰 입력을 줄이세요 |
429 | 요청 제한에 도달함 | Retry-After를 기다리세요 |
500–504 | 서비스 사용 불가 또는 네트워크 오류 | retryable이 true일 때만 재시도하고 retry_after와 횟수 제한을 준수하세요 |
일반적인 오류 코드
| 코드 | 의미 | 변경 사항 |
|---|---|---|
invalid_api_key | API 키가 없거나 유효하지 않거나 비활성화 또는 폐기됨 | Authorization 헤더와 키 값을 확인하세요 |
expired_api_key | API 키가 만료됨 | 활성 키를 생성하거나 선택하세요 |
insufficient_balance | 계정 잔액이 요청을 처리하기에 부족함 | 자금을 추가하거나, 요청을 줄이거나, 더 저렴한 모델을 선택하세요 |
quota_exceeded | API 키가 자체 제한에 도달함 | 해당 키의 제한을 늘리거나 다른 승인된 키를 사용하세요 |
model_not_allowed | 키가 요청된 모델을 사용할 수 없음 | 키의 모델 목록을 업데이트하거나 허용된 모델을 선택하세요 |
model_not_found | 모델 ID를 알 수 없거나 사용할 수 없음 | /v1/models를 읽고 현재 모델 ID를 사용하세요 |
context_length_exceeded | 입력이 모델이 허용하는 것보다 김 | 기록을 제거하거나 더 큰 컨텍스트 윈도우를 가진 모델을 선택하세요 |
rate_limit_exceeded | 현재 윈도우에서 너무 많은 요청이 전송됨 | Retry-After를 기다리세요 |
payload_too_large | 요청 본문이나 파일이 엔드포인트 제한을 초과함 | 입력을 줄이거나 압축하세요 |
all_channels_failed | 선택한 모델이 이 요청을 처리할 수 없음 | retryable이 true일 때만 재시도하고 retry_after와 횟수 제한을 준수하세요 |
timeout_error | 요청이 제시간에 완료되지 않음 | 작업 반복이 안전한 경우에만 재시도하세요 |
503 all_channels_failed 또는 503 delivery_tier_unavailable은 항상 일시적인 장애를 뜻하지 않습니다. 선택한 Delivery 등급에 요청한 작업을 제공하는 공급이 없으면 retryable은 false이고 retry_after는 반환되지 않습니다. 같은 요청을 반복하지 마세요. 다른 모델을 선택하기 전에 GET /v1/models로 작업과 Delivery의 사용 가능 여부를 확인하세요. 이름이 비슷하다고 사용 가능한 것은 아니며, 검증되지 않은 대체 모델은 표시하지 않습니다.
일부 OpenAI 호환 오류에는 선택적인 did_you_mean, suggestions, alternatives, hint, retryable 또는 retry_after 필드가 포함됩니다. 에이전트가 대응할 수 있는 오류를 참조하세요.
요청이 Official 경로에서 실행되었고 업스트림 서비스가 요청 자체를 거부한 경우(허용되지 않는 입력이나 콘텐츠 정책 판정 등) 오류에 upstream도 포함됩니다. message는 업스트림이 보고한 원문이며, 알려진 경우 code와 source(업스트림 서비스 이름)도 포함됩니다. Anthropic Messages와 Gemini 오류는 각자의 error 객체 안에 같은 필드를 담습니다. 분기는 계속 code와 type으로 처리하세요. upstream.code 값은 업스트림 서비스가 정의하며 바뀔 수 있습니다.
재시도 결정
| 오류 | 동일한 요청 반복 여부 |
|---|---|
400, 401, 402, 403, 404, 413 | 아니요. 요청, 자격 증명, 잔액, 권한 또는 입력을 변경하세요. |
429 | 예, 서버에서 제공한 지연 시간 이후에 시도하세요. |
500–504 | retryable이 true일 때만 재시도하고 retry_after와 횟수 제한을 준수하세요 |
| 응답 전 연결 종료 | 때때로. 생성 작업의 경우 작업이나 부작용이 이미 존재하는지 확인하세요. |
| 출력 도중 스트림 중단 | 완전한 응답으로 간주하지 마십시오. 반복 시 다른 출력이 생성되거나 이중 과금될 수 있습니다. |
이미지, 비디오, 음악, 3D 및 Worlds 생성의 경우, 작업 ID가 반환되는 즉시 저장하세요. 생성 요청 시간이 초과되면, 다른 생성 요청을 보내기 전에 작업 기록을 확인하세요.
Request ID 보관
응답 헤더에는 추적을 위한 Request ID가 포함되어 있습니다. 이를 엔드포인트, 모델, 시간 및 본인의 사용자 또는 작업 ID와 함께 저장하세요. 비동기 작업의 경우, task_id와 billing_transaction_id가 있을 때 함께 저장하세요.
지원팀에 문의할 때는 해당 ID와 수정된(redacted) 예시를 포함하세요. API 키, 관리 토큰, 개인 미디어, 서명된 URL 또는 전체 개인 프롬프트를 절대 보내지 마십시오.