TokenLab

핵심 가이드

에이전트가 처리할 수 있는 오류

프로즈(prose)를 파싱할 필요 없이 오류 코드, 재시도 타이밍 및 모델 제안을 사용하세요

이 페이지에서는 애플리케이션 및 코딩 에이전트를 위한 기계 판독 가능한 공개 API 오류에 대해 설명합니다. 이 페이지는 워크스페이스 요청 조사나 지원에 대한 액세스 권한을 부여하지 않습니다. 워크스페이스 내의 요청에 대해서는 요청 문제 해결부터 시작하세요.

OpenAI 호환 TokenLab 오류에는 에이전트나 애플리케이션을 위한 구조화된 힌트가 포함될 수 있습니다. 이러한 필드가 있을 때는 이를 사용하세요. 무엇을 해야 할지 결정하기 위해 사람이 읽을 수 있는 message를 파싱하지 마세요.

Anthropic Messages 및 Gemini API는 고유한 오류 형식을 유지하므로, 이 페이지의 확장은 OpenAI 호환 Chat Completions 및 Responses 오류에만 적용됩니다.

선택적 오류 필드

아래의 모든 필드는 error 객체 내부에 나타나며, 없을 수도 있습니다.

필드타입용도
did_you_meanstring단종된 모델에 대한 대체 모델 또는 가장 가까운 사용 가능한 모델 ID
suggestionsarray요청에 적합할 수 있는 모델들
hintstring간단한 설명 또는 제안된 조치
retryableboolean동일한 요청이 나중에 성공할 수 있는지 여부
retry_afternumber다시 시도하기 전까지 대기할 시간(초)
balance_usdnumberUSD 기준 현재 잔액
estimated_cost_usdnumber거부된 요청의 예상 비용
top_up_urlstring일부 insufficient_balance 오류 시 결제 페이지 링크
min_top_up_usdnumber일부 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

이 페이지의 내용