핵심 가이드
에이전트가 처리할 수 있는 오류
프로즈(prose)를 파싱할 필요 없이 오류 코드, 재시도 타이밍 및 모델 제안을 사용하세요
이 페이지에서는 애플리케이션 및 코딩 에이전트를 위한 기계 판독 가능한 공개 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 | 거부된 요청의 예상 비용 |
top_up_url | string | 일부 insufficient_balance 오류 시 결제 페이지 링크 |
min_top_up_usd | number | 일부 insufficient_balance 오류 시 최소 충전 금액(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 /v1/models to list all available models."
}
}잔액 부족
402 insufficient_balance에는 현재 잔액과 필요한 예상 금액, 또는 충전 링크와 최소 충전 금액이 포함될 수 있습니다. 애플리케이션은 충전 링크를 제공하거나, 더 저렴한 모델을 제안하거나, 더 작은 요청을 하도록 유도할 수 있습니다.
{
"error": {
"message": "Insufficient balance: this request needs about $0.35 for claude-sonnet-4-6, and your balance is $0.12. Add at least $5 to continue: https://tokenlab.sh/dashboard/billing · Why: https://tokenlab.sh/docs/en/quickstart#why-402 After you top up, your current API key works immediately, no new key needed.",
"type": "insufficient_balance",
"code": "insufficient_balance",
"retryable": false,
"balance_usd": 0.12,
"estimated_cost_usd": 0.35,
"suggestions": [
{"id": "gpt-5.6-luna"},
{"id": "deepseek-v4.1-flash"}
],
"hint": "Insufficient balance: need ~$0.350000 for claude-sonnet-4-6, but balance is $0.120000. 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 exceeded (1000/min for user role). Please retry later.",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"retryable": true,
"retry_after": 8,
"hint": "Rate limited. Retry after 8s. Current limit: 1000/min for user role."
}
}컨텍스트가 너무 긺
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, decision입니다. 생성 요청 시 선택한 모델 ID를 명시적으로 보내세요. TokenLab은 이를 다른 모델로 자동으로 대체하지 않습니다.
기계 판독 가능한 개요
에이전트는 다음 위치에서 간결한 API 개요를 읽을 수 있습니다:
GET https://api.tokenlab.sh/llms.txt여기에는 첫 번째 요청, 공통 엔드포인트, 모델 필터 및 오류 처리 지침이 포함되어 있습니다.
요청을 다시 실행하지 않고 오류 처리하기
이 예제는 요청을 한 번 수행하고, 선택한 모델을 유지하며, 구조화된 복구 정보를 보고합니다. 애플리케이션이 재시도가 안전한지 결정할 수 있도록 SDK 재시도는 비활성화되어 있습니다. 명시적인 선택을 위해 모델 제안을 제시하세요. 수락되었거나 시간 초과된 생성을 자동으로 다시 실행하지 마세요. 시간 초과된 요청을 안전하게 재시도하려면 Idempotency-Key로 안전하게 재시도하기에 표시된 대로 Idempotency-Key와 함께 보내세요.
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