TokenLab

핵심 가이드

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 또는 입력이 유효하지 않음요청을 수정하십시오. 변경 없이 반복하지 마십시오
401API 키가 없거나, 유효하지 않거나, 만료되었거나, 취소됨키를 교체하십시오
402잔액 또는 API 키 제한이 너무 낮음충전하거나, 제한을 높이거나, 요청을 줄이십시오
403이 키는 리소스나 모델을 사용할 수 없거나 계정이 제한됨키의 권한이나 모델을 변경하거나 지원팀에 문의하십시오
404리소스가 존재하지 않거나 더 이상 사용할 수 없음ID와 이를 생성한 API 키를 확인하십시오
409Idempotency-Key가 이미 사용됨: 다른 요청 본문(idempotency_conflict)과 함께 사용되었거나, TokenLab이 결과를 반환할 수 없는 요청(idempotency_replay_unavailable, idempotent_response_not_replayable)에 사용됨. TokenLab은 요청을 다시 실행하지 않았음새 요청에는 새 키를 사용하십시오. 동일한 키로 재시도할지 여부는 멱등성 키를 사용한 안전한 재시도를 참조하십시오
413요청 또는 업로드된 파일이 너무 큼문서화된 모델 또는 엔드포인트 제한에 맞게 입력을 줄이십시오
429요청 제한 도달Retry-After까지 대기하십시오
500–504서비스 이용 불가 또는 네트워크 오류retryable이 true인 경우에만 재시도하십시오. retry_after를 준수하고 시도 횟수를 제한하십시오

일반적인 오류 코드

코드의미변경할 사항
invalid_api_keyAPI 키가 없거나, 유효하지 않거나, 비활성 상태이거나, 취소됨Authorization 헤더와 키 값을 확인하십시오
expired_api_key키가 만료됨활성 키를 생성하거나 선택하십시오
insufficient_balance계정 잔액이 요청을 처리하기에 부족함자금을 추가하거나, 요청을 줄이거나, 더 저렴한 모델을 선택하십시오
quota_exceededAPI 키가 자체 제한에 도달함해당 키의 제한을 늘리거나 다른 승인된 키를 사용하십시오
model_not_allowed키가 요청된 모델을 사용할 수 없음키의 모델 목록을 업데이트하거나 허용된 모델을 선택하십시오
user_suspended, account_restrictedHTTP 403. 계정이 API를 사용할 수 없음Request ID와 함께 지원팀에 문의하십시오
invalid_delivery_policyHTTP 400. X-TokenLab-Delivery-Policy 헤더가 auto, verified, official이 아님세 가지 값 중 하나를 보내거나 헤더를 제거하십시오
model_not_found모델 ID를 알 수 없거나 사용할 수 없음/v1/models를 읽고 현재 모델 ID를 사용하십시오
context_length_exceeded입력이 모델 허용 범위를 초과함기록을 제거하거나 더 큰 컨텍스트 윈도우를 가진 모델을 선택하십시오
missing_required_parameter필수 필드가 누락됨. param이 필드 이름을 지정함(예: 기본 모델이 없는 오디오 및 이미지 요청의 model)param이 지정한 필드를 보내십시오
invalid_value필드에 모델이 허용하지 않는 값이 있음(예: reasoning_effort 값). 메시지에 허용되는 값이 나열됨나열된 값 중 하나를 사용하십시오
invalid_response_format_typeHTTP 400. response_format 이 객체이지만 사용할 수 있는 type 이 없거나, 이 엔드포인트가 허용하지 않는 type 입니다. param 은 response_format 입니다response_format.type 을 text, json_object, json_schema 중 하나로 설정하십시오. json_schema 인 경우 json_schema.name 과 json_schema.schema 도 함께 보내십시오
invalid_image_urlTokenLab이 이미지 URL을 사용할 수 없음: 유효한 HTTP(S) URL 또는 이미지 데이터 URI가 아니거나, 이미지 호스트가 이미지를 반환하지 않음. param이 필드 이름을 지정함공개 HTTPS 이미지 URL 또는 지원되는 데이터 URI를 보내십시오
unsupported_model_capability선택한 Delivery 티어의 어떤 경로도 작업, resolution, aspect_ratio, duration, 입력 미디어 필드, web_search_options, max_tokens와 같은 요청 매개변수를 지원하지 않음. 메시지에 일치하지 않는 각 매개변수와 모델이 게시하는 경우 지원되는 값이 나열됨매개변수를 제거하거나 변경하거나, 다른 Delivery 티어 또는 모델을 선택하십시오. 변경 없이 요청을 반복하지 마십시오
unpriceable_selection비디오 요청에 가격 책정에 필요한 선택기가 누락되어 TokenLab이 가격을 책정할 수 없음. param이 선택기 이름을 지정함param이 지정한 필드를 설정하십시오
model_pricing_unavailableHTTP 503. 요청은 유효하지만 TokenLab이 요청에서 사용할 수 있는 경로에서 해당 모델과 작업 조합의 가격을 책정할 수 없음. 요청에 대한 요금은 청구되지 않았으며 retryable은 false임변경 없이 요청을 반복하지 마십시오. 다른 모델이나 작업을 선택하거나 Request ID와 함께 지원팀에 문의하십시오
idempotency_conflictHTTP 409. Idempotency-Key가 다른 요청에 속함. TokenLab은 이 요청을 실행하지 않았음새 키로 새 요청을 보내십시오
idempotency_replay_unavailableHTTP 409. Idempotency-Key가 이미 사용되었으며 TokenLab이 반환할 결과가 없음. TokenLab은 이 요청을 다시 실행하지 않았음첫 번째 요청이 여전히 실행 중일 수 있다면 대기 후 동일한 키로 재시도하십시오. 그렇지 않으면 새 키를 보내십시오. 멱등성 키를 사용한 안전한 재시도를 참조하십시오
idempotent_response_not_replayableHTTP 409. Idempotency-Key가 작업이 이미 완료된 생성 요청에 속하며, TokenLab이 원래의 생성 응답을 반환할 수 없음. 응답 본문의 최상위 수준에 error와 함께 task_id가 포함됨. TokenLab은 이 요청을 다시 실행하지 않았음이 키로 요청을 반복하지 마십시오. 새 작업을 원하는 경우에만 새 키를 보내십시오
rate_limit_exceeded현재 윈도우에서 너무 많은 요청이 전송됨Retry-After까지 대기하십시오
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–504retryable이 true인 경우에만 재시도하십시오. retry_after를 준수하고 시도 횟수를 제한하십시오.
응답 전 연결 종료예, 멱등성 키를 사용한 안전한 재시도에 요청이 나열되어 있고 Idempotency-Key가 있는 경우: 동일한 키와 본문으로 다시 보내십시오. 그렇지 않으면 작업이나 부작용이 이미 존재하는지 먼저 확인하십시오.
출력 도착 후 스트림 중단완전한 응답으로 간주하지 마십시오. 반복 시 다른 출력이 생성되거나 두 번 청구될 수 있습니다.

이미지, 비디오, 음악, 3D 및 Worlds 생성의 경우, 작업 ID가 반환되는 즉시 저장하십시오. 생성 요청 시간이 초과되면 동일한 Idempotency-Key와 본문으로 다시 보내 원래 작업을 가져오십시오. 키가 없는 경우, 다른 생성 요청을 보내기 전에 작업 기록을 확인하십시오.

멱등성 키를 사용한 안전한 재시도

시간 초과나 연결 종료는 TokenLab이 요청을 실행했는지 여부를 알려주지 않습니다. 아래 나열된 요청에 Idempotency-Key 헤더를 추가하십시오. 그러면 동일한 요청을 재시도해도 두 번 실행되거나 청구되지 않습니다.

  • 각 작업마다 UUID와 같은 새 고유 값을 사용하십시오. 키는 최대 255자까지 가능합니다. TokenLab은 더 긴 키를 무시하며, 이 경우 요청은 멱등성 보호를 받지 못해 재시도 시 다시 실행되고 청구됩니다. POST /v1/messages/batches는 예외로, 256자가 넘는 키를 400 오류로 거부합니다.
  • 요청을 보내기 전에 자신의 작업 기록에 키를 저장하십시오.
  • 재시도 시 동일한 API 키, 동일한 Idempotency-Key, 동일한 본문을 보내십시오.
  • idempotency_replay_unavailable과 함께 409가 반환되는 경우를 제외하고, 응답을 받은 후에는 해당 키를 다시 사용하지 마십시오. 새로운 시도는 새 키로 보내십시오.
  • SDK 재시도(max_retries=0)를 끄고 코드가 키 재사용 시점을 결정하도록 하십시오.

헤더가 없으면 모든 재시도는 새로운 요청으로 간주됩니다.

작업을 생성하는 요청

이러한 생성 요청은 Idempotency-Key를 허용합니다:

  • POST /v1/videos/generations, POST /v1/music/generations, POST /v1/3d/generations, POST /v1/worlds/generations
  • 작업을 반환하는 POST /v1/images/generations 및 POST /v1/images/edits
  • "background": true인 POST /v1/responses
  • POST /v1/messages/batches

생성 요청 시간이 초과되면 변경 없이 다시 보내십시오. TokenLab은 원래 생성 요청의 결과를 반환하며 두 번째 작업을 생성, 발송 또는 청구하지 않습니다. 일반적으로 결과는 동일한 id를 가진 원래 작업(Responses의 경우 원래 응답 객체)이며, 계속해서 폴링할 수 있습니다. 비디오, 음악, 3D, Worlds 및 이미지 작업의 경우, 첫 번째 생성 요청이 실패했을 때 원래 오류가 결과가 될 수도 있습니다. 해당 작업이 이미 완료되었고 TokenLab에 저장된 생성 응답이 없는 경우, 재시도는 idempotent_response_not_replayable 코드와 함께 409를 반환하며 응답 본문의 최상위 수준에 task_id가 포함됩니다.

TokenLab이 이미 수락한 키로 다른 본문을 보내면, TokenLab은 요청을 거부하고 작업을 생성하지 않습니다. 비디오, 음악, 3D 및 Worlds 생성 요청은 idempotency_conflict 코드와 함께 409를 반환합니다. Message Batches는 conflict_error 오류 유형과 함께 409를 반환합니다. 이미지 작업 및 background: true인 Responses 요청의 경우, 이 경우에 대한 상태 코드와 오류 코드는 보장되지 않습니다. 동일한 키로 요청을 재시도하지 마십시오.

Chat Completions, Responses 및 Messages

POST /v1/chat/completions, background가 없는 POST /v1/responses, POST /v1/messages는 주어진 키로 요청을 한 번만 실행합니다. 동일한 키로 재시도하면 다음 결과 중 하나가 발생합니다:

상황결과
첫 번째 요청이 여전히 실행 중임idempotency_replay_unavailable 코드와 함께 409
클라이언트 연결이 끊긴 후 첫 번째 요청이 완료됨. 요청이 스트리밍되지 않았고, 결과가 1MB 이하이며, 24시간 이내에 동일한 본문으로 재시도함원래 응답 본문과 Idempotent-Replayed: true 헤더와 함께 200. TokenLab은 요청을 다시 실행하거나 청구하지 않음
키가 다른 방식으로 사용됨(예: 결과를 받았거나, 요청이 스트리밍되었거나, 결과가 1MB보다 크거나, 24시간이 지남)idempotency_replay_unavailable 코드와 함께 409
본문이 첫 번째 요청과 다름409, 일반적으로 idempotency_conflict 코드와 함께 반환됨. 일부 요청은 idempotency_replay_unavailable을 반환함

어느 코드든 409는 TokenLab이 요청을 다시 실행하지 않았음을 의미합니다. 키가 있는 스트리밍 요청은 두 번 실행될 수 없지만, TokenLab은 출력을 다시 보낼 수 없습니다.

다음 예제는 시간이 초과된 Chat Completions 요청을 결과가 나올 때까지 동일한 키로 재시도합니다:

import os
import time
import uuid
import openai
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=120.0,
    max_retries=0,
)

def create_once(messages, model="gpt-5.6-terra", waits=(0, 5, 15, 45)):
    key = str(uuid.uuid4())  # 이 키를 작업 기록과 함께 저장하십시오.
    for wait in waits:
        time.sleep(wait)
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
                extra_headers={"Idempotency-Key": key},
            )
        except (openai.APITimeoutError, openai.APIConnectionError):
            continue  # 응답 없음: 동일한 키와 본문으로 재시도하십시오.
        except openai.ConflictError as exc:
            if exc.code != "idempotency_replay_unavailable":
                raise
            # 첫 번째 시도가 여전히 실행 중일 수 있습니다. 이후 재시도 시 결과가 반환됩니다.
    raise RuntimeError(f"No result for Idempotency-Key {key}")

마지막 시도에서도 idempotency_replay_unavailable이 반환되면 TokenLab은 해당 결과를 반환할 수 없습니다. 두 번째 실행과 두 번째 청구가 허용되는 경우에만 새 키로 요청을 보내십시오.

Request ID 보관

응답 헤더에는 추적을 위한 Request ID가 포함되어 있습니다. 이를 엔드포인트, 모델, 시간 및 사용자 또는 작업 ID와 함께 저장하십시오. 비동기 작업의 경우, task_id와 billing_transaction_id가 있으면 함께 저장하십시오.

지원팀에 문의할 때는 해당 ID와 수정된(redacted) 예제를 포함하십시오. API 키, 관리 토큰, 개인 미디어, 서명된 URL 또는 전체 개인 프롬프트를 절대 보내지 마십시오.

요청에서 조사 및 지원까지

이 페이지의 내용