Guías principales

Manejo de errores de la API

Lea los códigos de error, reintente solo cuando sea útil y conserve el Request ID

Maneje los errores mediante el estado HTTP y el code. El message está escrito para personas y puede cambiar sin previo aviso.

Chat Completions y Responses utilizan un objeto error al estilo de OpenAI. Anthropic Messages y Gemini mantienen sus propios formatos de error, por lo que no debe utilizar un único analizador para toda la API de TokenLab.

{
  "error": {
    "message": "Human-readable description",
    "type": "error_type",
    "code": "error_code",
    "param": "parameter_name",
    "retryable": true,
    "retry_after": 30
  }
}

Solo message y type están siempre presentes en los errores compatibles con OpenAI creados por TokenLab. Otros campos aparecen cuando son relevantes.

Códigos de estado

EstadoSignificadoAcción típica
400Un campo, ID de modelo o entrada no es válidoCorrija la solicitud; no la repita sin cambios
401La API key falta, no es válida, ha caducado o ha sido revocadaReemplace la clave
402El saldo o el límite de la API key es demasiado bajoRecargue, aumente el límite o reduzca la solicitud
403Esta clave no puede usar el recurso o modelo, o la cuenta está restringidaCambie los permisos o el modelo de la clave, o contacte a soporte
404El recurso no existe o ya no está disponibleVerifique el ID y la API key que lo creó
409La Idempotency-Key ya se utilizó: con un cuerpo de solicitud diferente (idempotency_conflict), o para una solicitud cuyo resultado TokenLab no puede devolver (idempotency_replay_unavailable, idempotent_response_not_replayable). TokenLab no ejecutó la solicitud de nuevoUse una clave nueva para una solicitud nueva. Para decidir si reintentar con la misma clave, consulte Reintente de forma segura con una idempotency key
413La solicitud o el archivo cargado es demasiado grandeReduzca la entrada al límite documentado del modelo o endpoint
429Se alcanzó el límite de solicitudesEspere según Retry-After
500–504Servicio no disponible o fallo de redReintente solo cuando retryable sea true; respete retry_after y limite los intentos

Códigos de error comunes

CódigoQué significaQué cambiar
invalid_api_keyLa API key falta, no es válida, está inactiva o fue revocadaVerifique el encabezado Authorization y el valor de la clave
expired_api_keyLa clave ha caducadoCree o seleccione una clave activa
insufficient_balanceEl saldo de la cuenta no puede cubrir la solicitudAgregue fondos, reduzca la solicitud o elija un modelo de menor precio
quota_exceededLa API key alcanzó su propio límiteAumente el límite de esa clave o use otra clave autorizada
model_not_allowedLa clave no puede usar el modelo solicitadoActualice la lista de modelos de la clave o elija un modelo permitido
user_suspended, account_restrictedHTTP 403. La cuenta no puede usar la APIContacte a soporte con el Request ID
invalid_delivery_policyHTTP 400. El encabezado X-TokenLab-Delivery-Policy no es auto, verified o officialEnvíe uno de los tres valores o elimine el encabezado
model_not_foundEl ID del modelo es desconocido o no está disponibleLea /v1/models y use un ID de modelo actual
context_length_exceededLa entrada es más larga de lo que acepta el modeloElimine historial o elija un modelo con una ventana de contexto mayor
missing_required_parameterFalta un campo obligatorio. param lo nombra, por ejemplo model en solicitudes de audio e imagen, que no tienen modelo predeterminadoEnvíe el campo que nombra param
invalid_valueUn campo tiene un valor que el modelo no acepta, por ejemplo un valor de reasoning_effort. El mensaje enumera los valores aceptadosUse uno de los valores enumerados
invalid_response_format_typeHTTP 400. response_format es un objeto sin un type utilizable, o con un type que este endpoint no acepta. param es response_formatEstablezca response_format.type en text, json_object o json_schema; con json_schema, envíe también json_schema.name y json_schema.schema
invalid_image_urlTokenLab no puede usar una URL de imagen: no es una URL HTTP(S) válida o un URI de datos de imagen, o el host de la imagen no devolvió la imagen. param nombra el campoEnvíe una URL de imagen HTTPS pública o un URI de datos compatible
unsupported_model_capabilityNinguna ruta del nivel de Delivery seleccionado admite un parámetro de solicitud, como la operación, resolution, aspect_ratio, duration, un campo de entrada multimedia, web_search_options o max_tokens. El mensaje nombra cada parámetro que no coincidió y, cuando el modelo los publica, los valores admitidosElimine o cambie el parámetro, o elija otro nivel de Delivery o modelo; no repita la solicitud sin cambios
unpriceable_selectionLa solicitud de video omite un selector del cual depende su precio, por lo que TokenLab no puede calcularlo. param nombra el selectorEstablezca el campo que nombra param
model_pricing_unavailableHTTP 503. La solicitud es válida, pero TokenLab no puede calcular el precio de esta combinación de modelo y operación en las rutas que la solicitud puede usar. No se cobró la solicitud y retryable es falseNo repita la solicitud sin cambios; elija otro modelo u operación, o contacte a soporte con el Request ID
idempotency_conflictHTTP 409. La Idempotency-Key pertenece a una solicitud diferente. TokenLab no ejecutó esta solicitudEnvíe una solicitud nueva con una clave nueva
idempotency_replay_unavailableHTTP 409. La Idempotency-Key ya se utilizó y TokenLab no tiene resultado que devolver. TokenLab no ejecutó esta solicitud de nuevoSi la primera solicitud aún puede estar ejecutándose, espere y reintente con la misma clave. De lo contrario, envíe una clave nueva. Consulte Reintente de forma segura con una idempotency key
idempotent_response_not_replayableHTTP 409. La Idempotency-Key pertenece a una solicitud de creación cuya tarea ya terminó, y TokenLab no puede devolver la respuesta de creación original. El nivel superior del cuerpo de la respuesta incluye task_id, junto a error. TokenLab no ejecutó esta solicitud de nuevoNo repita la solicitud con esta clave. Envíe una clave nueva solo si desea una tarea nueva
rate_limit_exceededSe enviaron demasiadas solicitudes en la ventana actualEspere según Retry-After
all_channels_failedEl modelo seleccionado no puede atender esta solicitudReintente solo cuando retryable sea true; respete retry_after y limite los intentos
timeout_errorLa solicitud no terminó a tiempoReintente solo cuando la operación sea segura de repetir

Un 503 all_channels_failed o 503 delivery_tier_unavailable no siempre significa una interrupción temporal. Si la operación solicitada no tiene suministro en el nivel de Delivery seleccionado, retryable es false y retry_after se omite. No repita la misma solicitud. Verifique la disponibilidad de la operación y del Delivery con GET /v1/models antes de seleccionar otro modelo. Los nombres similares no garantizan disponibilidad; las alternativas no verificadas se omiten.

Algunos errores compatibles con OpenAI incluyen campos opcionales did_you_mean, suggestions, alternatives, hint, retryable o retry_after. Consulte Errores sobre los que los agentes pueden actuar.

Cuando una solicitud se ejecutó en una ruta Official y el servicio upstream rechazó la solicitud en sí, como una entrada que no acepta o una decisión de política de contenido, el error también lleva upstream: el message del upstream según se informó, además de code y source (el nombre del servicio upstream) cuando se conocen. Los errores de Anthropic Messages y Gemini llevan el mismo objeto dentro de su propio error. Siga ramificando según code y type; los valores de upstream.code son definidos por el servicio upstream y pueden cambiar.

Decisiones de reintento

Error¿Repetir la misma solicitud?
400, 401, 402, 403, 404, 413No. Cambie la solicitud, las credenciales, el saldo, los permisos o la entrada.
429Sí, después de la demora proporcionada por el servidor.
500–504Reintente solo cuando retryable sea true; respete retry_after y limite los intentos
Conexión cerrada antes de cualquier respuestaSí, cuando la solicitud aparece en Reintente de forma segura con una idempotency key y tiene una Idempotency-Key: envíela de nuevo con la misma clave y cuerpo. De lo contrario, primero verifique si ya existe una tarea o efecto secundario.
Flujo interrumpido después de que llegó la salidaNo lo llame una respuesta completa. Repetir puede generar una salida diferente o un segundo cargo.

Para la creación de imágenes, video, música, 3D y Worlds, guarde el ID de la tarea tan pronto como se devuelva. Si una solicitud de creación agota el tiempo de espera, envíela de nuevo con la misma Idempotency-Key y cuerpo para obtener la tarea original. Sin una clave, verifique el registro de la tarea antes de enviar otra solicitud de creación.

Reintente de forma segura con una idempotency key

Un tiempo de espera o una conexión cerrada no le indican si TokenLab ejecutó la solicitud. Agregue un encabezado Idempotency-Key a las solicitudes enumeradas a continuación. Entonces, un reintento de la misma solicitud no puede ejecutarla ni cobrarla por segunda vez.

  • Use un valor único nuevo para cada operación, por ejemplo un UUID. Una clave puede tener hasta 255 caracteres. TokenLab ignora una clave más larga, y la solicitud entonces no tiene protección de idempotencia: un reintento se ejecuta y se cobra de nuevo. POST /v1/messages/batches es diferente: rechaza una clave de más de 256 caracteres con 400.
  • Guarde la clave con su propio registro de trabajo antes de enviar la solicitud.
  • Cuando reintente, envíe la misma API key, la misma Idempotency-Key y el mismo cuerpo.
  • Después de cualquier respuesta que no sea 409 con idempotency_replay_unavailable, no vuelva a usar esa clave. Envíe cualquier intento nuevo con una clave nueva.
  • Desactive los reintentos del SDK (max_retries=0), para que su código decida cuándo reutilizar una clave.

Sin el encabezado, cada reintento es una solicitud nueva.

Solicitudes que crean una tarea

Estas solicitudes de creación aceptan Idempotency-Key:

  • POST /v1/videos/generations, POST /v1/music/generations, POST /v1/3d/generations y POST /v1/worlds/generations
  • POST /v1/images/generations y POST /v1/images/edits cuando devuelven una tarea
  • POST /v1/responses con "background": true
  • POST /v1/messages/batches

Si una solicitud de creación agota el tiempo de espera, envíela de nuevo sin cambios. TokenLab devuelve el resultado de la solicitud de creación original y no crea, despacha ni cobra una segunda tarea. Por lo general, el resultado es la tarea original con el mismo id (para Responses, el objeto de respuesta original), y usted continúa consultándolo. Para tareas de video, música, 3D, Worlds e imágenes, el resultado también puede ser el error original cuando falló la primera solicitud de creación. Si dicha tarea ya terminó y TokenLab no tiene una respuesta de creación almacenada, el reintento devuelve 409 con el código idempotent_response_not_replayable, y el nivel superior del cuerpo de la respuesta incluye task_id.

Si envía un cuerpo diferente con una clave que TokenLab ya aceptó, TokenLab rechaza la solicitud y no crea una tarea. Las solicitudes de creación de video, música, 3D y Worlds devuelven 409 con el código idempotency_conflict. Message Batches devuelve 409 con el tipo de error conflict_error. Para tareas de imágenes y para solicitudes de Responses con background: true, el código de estado y el código de error para este caso no están garantizados. No repita la solicitud con la misma clave.

Chat Completions, Responses y Messages

POST /v1/chat/completions, POST /v1/responses sin background y POST /v1/messages ejecutan una solicitud con una clave dada solo una vez. Un reintento con la misma clave obtiene uno de estos resultados:

SituaciónResultado
La primera solicitud aún se está ejecutando409 con el código idempotency_replay_unavailable
La primera solicitud terminó después de que su cliente se desconectó. La solicitud no se transmitió, el resultado es de 1 MB o menos, y usted reintenta con el mismo cuerpo dentro de las 24 horas200 con el cuerpo de respuesta original y el encabezado Idempotent-Replayed: true. TokenLab no ejecuta ni cobra la solicitud de nuevo
La clave se usó de cualquier otra manera, por ejemplo: recibió el resultado, la solicitud se transmitió, el resultado era mayor a 1 MB o pasaron más de 24 horas409 con el código idempotency_replay_unavailable
El cuerpo es diferente al de la primera solicitud409, generalmente con el código idempotency_conflict. Algunas solicitudes devuelven idempotency_replay_unavailable

Un 409 con cualquiera de los códigos significa que TokenLab no ejecutó la solicitud de nuevo. Una solicitud transmitida con una clave no puede ejecutarse dos veces, pero TokenLab no puede enviar su salida de nuevo.

Este ejemplo reintenta una solicitud de Chat Completions que agotó el tiempo de espera con la misma clave hasta que obtiene el resultado:

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())  # Save this key with your job record.
    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  # No response: retry with the same key and body.
        except openai.ConflictError as exc:
            if exc.code != "idempotency_replay_unavailable":
                raise
            # The first attempt can still be running. A later retry returns its result.
    raise RuntimeError(f"No result for Idempotency-Key {key}")

Si el último intento aún devuelve idempotency_replay_unavailable, TokenLab no puede devolver ese resultado. Envíe la solicitud con una clave nueva solo si una segunda ejecución y un segundo cargo son aceptables.

Conserve el Request ID

Los encabezados de respuesta incluyen un Request ID para el rastreo. Guárdelo junto con el endpoint, el modelo, la hora y su propio ID de usuario o de trabajo. Para el trabajo asíncrono, guarde también task_id y billing_transaction_id cuando estén presentes.

Al contactar a soporte, incluya esos IDs y un ejemplo redactado. Nunca envíe API keys, tokens de gestión, medios privados, URLs firmadas o prompts privados completos.

De una solicitud a una investigación y soporte

En esta página