핵심 가이드
에이전트가 대응할 수 있는 오류
프로세스를 파싱하지 않고도 오류 코드, 재시도 타이밍, 모델 제안을 활용하세요
이 페이지는 앱과 코딩 에이전트가 읽는 공개 API 오류를 설명합니다. 워크스페이스 요청 조사나 지원 권한을 부여하지 않습니다. 자신의 요청은 문제 해결 가이드에서 시작하세요.
OpenAI 호환 TokenLab 오류에는 에이전트나 애플리케이션을 위한 구조화된 힌트가 포함될 수 있습니다. 이러한 필드가 존재할 경우 이를 사용하십시오. 무엇을 해야 할지 결정하기 위해 사람이 읽을 수 있는 message를 파싱하지 마십시오.
Anthropic Messages 및 Gemini API는 고유한 오류 형식을 유지하므로, 이 페이지의 확장 기능은 OpenAI 호환 Chat Completions 및 Responses 오류에만 적용됩니다.
선택적 오류 필드
아래의 모든 필드는 error 객체 내부에 나타나며, 없을 수도 있습니다.
| 필드 | 타입 | 용도 |
|---|---|---|
did_you_mean | string | 가장 근접한 사용 가능한 모델 ID |
suggestions | array | 요청에 적합할 수 있는 모델들 |
hint | string | 간단한 설명 또는 제안된 조치 |
retryable | boolean | 동일한 요청이 나중에 성공할 수 있는지 여부 |
retry_after | number | 재시도 전 대기 시간(초) |
balance_usd | number | 현재 잔액(USD) |
estimated_cost_usd | number | 거부된 요청의 예상 비용(USD) |
클라이언트는 여전히 HTTP 상태 코드와 code를 통해 모든 오류를 처리해야 합니다. 이러한 추가 필드는 유용한 컨텍스트로 취급하되, 필수 필드로 간주하지 마십시오.
알 수 없는 모델
철자가 틀렸거나 사용할 수 없는 모델은 400 model_not_found를 반환합니다. did_you_mean이 있는 경우, 사용자에게 이를 보여주거나 제품에서 이미 선택된 모델을 변경할 권한이 있는 경우에만 재시도하십시오.
{
"error": {
"message": "Model not found: please check the model name",
"type": "invalid_request_error",
"param": "model",
"code": "model_not_found",
"did_you_mean": "gpt-5.6-terra",
"suggestions": [
{"id": "gpt-5.6-terra"},
{"id": "gpt-5.6-luna"}
],
"hint": "Did you mean 'gpt-5.6-terra'? Use GET https://api.tokenlab.sh/v1/models to list all available models."
}
}잔액 부족
402 insufficient_balance에는 현재 잔액과 필요한 예상 금액이 포함될 수 있습니다. 애플리케이션은 충전 링크를 제공하거나, 더 저렴한 모델을 제안하거나, 더 작은 요청을 하도록 유도할 수 있습니다.
{
"error": {
"message": "Insufficient balance: need ~$0.3500 for claude-sonnet-4-6, but balance is $0.1200.",
"type": "insufficient_balance",
"code": "insufficient_balance",
"balance_usd": 0.12,
"estimated_cost_usd": 0.35,
"suggestions": [
{"id": "gpt-5.6-luna"},
{"id": "deepseek-v3-2"}
],
"hint": "Try a cheaper model, or top up at https://tokenlab.sh/dashboard/billing."
}
}모델을 사용할 수 없는 경우
503 all_channels_failed 또는 503 delivery_tier_unavailable은 항상 일시적인 장애를 뜻하지 않습니다. 선택한 Delivery 등급에 요청한 작업을 제공하는 공급이 없으면 retryable은 false이고 retry_after는 반환되지 않습니다. 같은 요청을 반복하지 마세요. 다른 모델을 선택하기 전에 GET /v1/models로 작업과 Delivery의 사용 가능 여부를 확인하세요. 이름이 비슷하다고 사용 가능한 것은 아니며, 검증되지 않은 대체 모델은 표시하지 않습니다.
{
"error": {
"message": "This model is unavailable for the requested operation and Delivery tier.",
"type": "all_channels_failed",
"code": "all_channels_failed",
"retryable": false,
"hint": "Check the model's operation and Delivery availability with GET /v1/models. Repeating the same request will not resolve this."
}
}속도 제한
429 rate_limit_exceeded의 경우, retry_after 초만큼 기다리거나 표준 Retry-After 응답 헤더를 사용하십시오.
{
"error": {
"message": "Rate limit: 1000 rpm exceeded",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"retryable": true,
"retry_after": 8,
"hint": "Retry after 8s."
}
}컨텍스트가 너무 긺
400 context_length_exceeded는 동일한 요청을 다시 보내는 것으로 해결되지 않습니다. 입력을 줄이거나 사용자가 더 큰 컨텍스트 윈도우를 가진 모델을 선택하도록 하십시오.
{
"error": {
"message": "This model's maximum context length is 128000 tokens...",
"type": "invalid_request_error",
"code": "context_length_exceeded",
"retryable": false,
"suggestions": [
{"id": "gemini-2.5-pro"},
{"id": "claude-sonnet-5"}
],
"hint": "Reduce your input or switch to a model with a larger context window."
}
}올바른 API 형식 찾기
모델별 API를 사용하기 전에 GET /v1/models/{model}에서 tokenlab.accepted_request_formats를 읽으십시오.
| 값 | 엔드포인트 |
|---|---|
openai_chat_completions | /v1/chat/completions |
openai_responses | /v1/responses |
anthropic_messages | /v1/messages |
gemini_generate_content | /v1beta/models/{model}:generateContent |
허용된 형식은 엔드포인트를 확인해 줍니다. 개별 도구와 필드는 모델마다 다를 수 있으므로, 의존하기 전에 모델 페이지를 확인하십시오.
작업별 모델 찾기
Models API는 채팅 이외의 작업에 대한 현재 추천 목록을 반환할 수 있습니다:
curl "https://api.tokenlab.sh/v1/models?recommended_for=image"유효한 recommended_for 값은 image, video, music, 3d, tts, stt, embedding, rerank, translation입니다. 생성 요청 시 선택한 모델 ID를 명시적으로 보내십시오. TokenLab은 이를 다른 모델로 자동으로 대체하지 않습니다.
기계 판독 가능한 개요
에이전트는 다음 위치에서 간결한 API 개요를 읽을 수 있습니다:
GET https://api.tokenlab.sh/llms.txt여기에는 첫 번째 요청, 일반적인 엔드포인트, 모델 필터 및 오류 처리 지침이 포함되어 있습니다.
요청을 다시 보내지 않고 오류 처리
이 예제는 요청을 한 번만 보내고 선택한 모델을 유지하며 구조화된 오류 정보를 표시합니다. SDK 자동 재시도는 비활성화되어 있습니다. 모델 제안은 사용자가 직접 선택하게 하세요. 수락되었거나 시간이 초과된 생성 요청을 자동으로 다시 보내지 마세요.
import os
from openai import OpenAI, APIStatusError
with OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=30.0,
max_retries=0,
) as client:
try:
response = client.chat.completions.create(
model="gpt-5.6-terra",
messages=[{"role": "user", "content": "Reply only with OK."}],
)
print(response.choices[0].message.content)
except APIStatusError as exc:
body = exc.body if isinstance(exc.body, dict) else {}
error = body.get("error", body)
if not isinstance(error, dict):
error = {}
print({
"status": exc.status_code,
"request_id": exc.request_id,
"code": error.get("code"),
"hint": error.get("hint"),
"suggested_model": error.get("did_you_mean"),
"retry_after": exc.response.headers.get("Retry-After") or error.get("retry_after"),
})
raise