Errores de la API de BetterToken: códigos HTTP y límites

Diagnostica un error de la API de BetterToken combinando el estado HTTP y el cuerpo de la respuesta. Anota el ID de solicitud de error.message, corrige los errores de autenticación o configuración antes de reenviar y reintenta solo los fallos identificados como temporales.

Antes de diagnosticar el problema

Ten a mano el Model ID, la Base URL y la respuesta fallida. Comprueba el estado de la Key y el saldo actual en el Dashboard de BetterToken. Si aún no has completado una solicitud a un modelo, empieza por los ejemplos de SDK o la guía de configuración de tu herramienta.

Interpreta la respuesta de error

BetterToken devuelve los errores de la API en una estructura JSON. Por ejemplo, una solicitud sin Key puede devolver:

{
  "error": {
    "code": "",
    "message": "Token not provided (request id: …)",
    "type": "new_api_error"
  }
}

Lee error.message aunque error.code esté vacío. El ID de solicitud de ese mensaje ayuda a identificar el intento fallido. Una solicitud a /v1/models sin Key devuelve 401; no comprueba si tu modelo puede generar una respuesta. Anota estos datos antes de contactar con soporte:

Dato	Qué anotar
Estado HTTP	Estado de la respuesta o excepción de red o tiempo de espera del cliente si no hubo respuesta HTTP
Cuerpo de la respuesta	JSON de error u otro contenido recibido, sin secretos
ID de solicitud	Identificador de `error.message`, si aparece
Hora	Fecha, hora y zona horaria del intento
Model ID	Valor exacto enviado como `model`
Base URL	Base URL configurada y ruta final de la solicitud

No incluyas tu BetterToken API Key en capturas, mensajes de soporte ni registros compartidos.

Comprueba el estado HTTP

La tabla recoge los significados generales de HTTP y las API, junto con las guías de configuración enlazadas. No es una lista de códigos específicos de BetterToken; lee la respuesta real antes de elegir una solución.

Estado	Significado habitual	Qué comprobar primero	¿Reintentar?
`400`	Solicitud, campo o combinación de parámetros no válidos	Estructura JSON, campos obligatorios, modelo y especificación del endpoint	Corrige primero la solicitud
`401`	Credencial ausente, no válida, caducada o revocada	Estado de la Key, espacios y cabecera de autenticación del protocolo	Corrige primero la autenticación
`403`	Solicitud rechazada	Mensaje de respuesta, saldo, estado de la Key y configuración del cliente	Resuelve primero el rechazo
`404`	Ruta o recurso no encontrado	Base URL, `/v1` duplicado o ausente, ruta final y Model ID exacto	Corrige primero la URL o el recurso
`408` / tiempo de espera del cliente	El servidor no recibió la solicitud completa a tiempo o el cliente dejó de esperar	Si se recibió un estado HTTP, ajustes de tiempo de espera, red y estado de la solicitud en el Dashboard	Comprueba si la solicitud terminó antes de decidir
`409` / `422`, si se devuelven	Generalmente, conflicto o contenido que no se puede procesar	Detalles de la respuesta y estado o campos enviados	Resuelve primero la causa
`429`	Se alcanzó un límite	Cuerpo de la respuesta y cabeceras de reintento; consulta las preguntas sobre diagnóstico de límites	Solo si se identifica un límite temporal de solicitudes
`500`	Fallo del servidor	Registro de la solicitud, mensaje y persistencia del fallo	Reintentos limitados si el fallo es temporal
`502` / `503`	Fallo del gateway o servicio de origen, o indisponibilidad temporal	Cuerpo de la respuesta y cabecera `Retry-After`, si aparece	Reintentos limitados si el fallo es temporal
`504`	El gateway agotó el tiempo de espera de la respuesta del servicio de origen	Registro del Dashboard y si la solicitud terminó	Comprueba la finalización antes de reintentar

Para errores de protocolo o sufijo, consulta las preguntas sobre Base URL. Para dudas sobre caché, consulta las preguntas sobre facturación de la caché.

Reintenta los fallos temporales

Tras identificar un 429 temporal o un fallo temporal del servidor, usa una espera exponencial con variación aleatoria y límites. Respeta Retry-After si se devuelve; si supera tu límite de reintentos, detén el bucle y espera fuera de él. Los reintentos del SDK y los de tu bucle comparten un mismo máximo de intentos; desactiva los del SDK si implementas tu propia política. No reintentes sin cambios los errores 400, 401, 403, de saldo o de configuración. Un tiempo de espera agotado o un flujo interrumpido no demuestra que la solicitud fallara antes de procesarse. Comprueba primero el Dashboard, sobre todo al generar imágenes o en flujos que puedan repetir una acción. Los siguientes ejemplos envían una solicitud a Chat Completions sin streaming, con un máximo de cuatro intentos. Reintentan los estados HTTP 500, 502 y 503. Los reintentos de 429 permanecen desactivados hasta confirmar que se trata de un límite temporal, y se detienen ante tiempos de espera agotados, excepciones de red y 504 para que compruebes si la solicitud terminó. La espera máxima por reintento es de 30 segundos.

Prepara la solicitud

Copia un Model ID actual del model plaza y sustituye los dos valores de ejemplo. Usa un modelo de texto disponible mediante Chat Completions.

export BETTERTOKEN_API_KEY="YOUR_API_KEY"
export BETTERTOKEN_MODEL_ID="YOUR_MODEL_ID"

El ejemplo de Python usa la biblioteca estándar. Guarda el ejemplo de JavaScript en un archivo .mjs y ejecútalo con una versión de Node.js que incluya fetch y AbortSignal.timeout.

Python
JavaScript

import json
import os
import random
import time
import urllib.error
import urllib.request
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime

def retry_after_seconds(value):
    try:
        return max(0.0, float(value))
    except ValueError:
        return max(0.0, (
            parsedate_to_datetime(value) - datetime.now(timezone.utc)
        ).total_seconds())

retry_temporary_429 = False  # Enable only after diagnosing the returned limit.
payload = json.dumps({
    "model": os.environ["BETTERTOKEN_MODEL_ID"],
    "messages": [{"role": "user", "content": "Reply with one word: OK"}],
}).encode()
for attempt in range(4):
    request = urllib.request.Request(
        "https://bettertoken.ai/v1/chat/completions", data=payload,
        headers={
            "Authorization": "Bearer " + os.environ["BETTERTOKEN_API_KEY"],
            "Content-Type": "application/json",
        },
    )
    try:
        with urllib.request.urlopen(request, timeout=120) as response:
            print(json.load(response)["choices"][0]["message"]["content"])
        break
    except urllib.error.HTTPError as error:
        body = error.read().decode("utf-8", errors="replace")
        retryable = error.code in (500, 502, 503) or (
            error.code == 429 and retry_temporary_429
        )
        if not retryable or attempt == 3:
            raise RuntimeError(f"HTTP {error.code}: {body}") from error
        delay = random.uniform(0, min(8.0, 2.0 ** attempt))
        retry_after = error.headers.get("Retry-After")
        if retry_after:
            delay = max(delay, retry_after_seconds(retry_after))
        if delay > 30:
            raise RuntimeError("Retry-After exceeds this retry budget") from error
        time.sleep(delay)

const retryTemporary429 = false; // Enable only after diagnosing the returned limit.
const payload = {
  model: process.env.BETTERTOKEN_MODEL_ID,
  messages: [{ role: "user", content: "Reply with one word: OK" }],
};
for (let attempt = 0; attempt < 4; attempt++) {
  const response = await fetch("https://bettertoken.ai/v1/chat/completions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BETTERTOKEN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
    signal: AbortSignal.timeout(120000),
  });
  const body = await response.text();
  if (response.ok) {
    console.log(JSON.parse(body).choices[0].message.content);
    break;
  }
  const retryable = [500, 502, 503].includes(response.status) ||
    (response.status === 429 && retryTemporary429);
  if (!retryable || attempt === 3) {
    throw new Error(`HTTP ${response.status}: ${body}`);
  }
  let delay = Math.random() * Math.min(8000, 1000 * 2 ** attempt);
  const retryAfter = response.headers.get("Retry-After");
  if (retryAfter !== null) {
    const seconds = Number(retryAfter);
    const wait = Number.isFinite(seconds)
      ? seconds * 1000 : Date.parse(retryAfter) - Date.now();
    if (!Number.isFinite(wait)) throw new Error("Invalid Retry-After header");
    delay = Math.max(delay, wait, 0);
  }
  if (delay > 30000) throw new Error("Retry-After exceeds this retry budget");
  await new Promise(resolve => setTimeout(resolve, delay));
}

Si el cuerpo de la respuesta indica un problema persistente de configuración, saldo o acceso, detén el bucle y corrígelo aunque el estado por sí solo parezca admitir reintentos. Antes de usar este ejemplo breve de texto para otras operaciones, adáptalo a las comprobaciones de finalización de tu aplicación.

Busca la guía para tu caso

Síntoma	Guía
Error de autenticación, URL o modelo en Claude Code	Errores frecuentes de Claude Code
Codex pide iniciar sesión o ignora los cambios de proveedor	Errores frecuentes de Codex CLI / App
No se puede activar la Key de Cursor o dejan de funcionar los modelos integrados	Errores frecuentes de Cursor
Error de autenticación, `404` o modelo en Cline	Errores frecuentes de Cline
Error de proveedor, modelo o configuración del proyecto en OpenCode	Errores frecuentes de OpenCode
El Gateway de Claude Desktop no se conecta	Errores frecuentes de Claude Desktop
Aviso de uso de Codex oficial o `429` de la API	Límite de uso frente a límite de solicitudes de la API
Los cambios parecen no tener efecto	Eliminar variables de entorno en conflicto
Salida truncada o error de límite de salida	Límites de tokens de salida

Confirma la solución

Envía una solicitud breve y no crítica con el mismo cliente, Base URL y Model ID que fallaron. Confirma que recibes una respuesta normal y busca el registro correspondiente en el Dashboard. Comprueba el modelo, el estado, el uso de tokens y el cargo antes de retomar un flujo más amplio.

Preguntas frecuentes

¿Todos los errores 429 requieren esperar y reintentar?

Consulta las preguntas sobre diagnóstico de límites de uso para decidir qué comprobar y si corresponde reintentar tu respuesta.

¿Debo aumentar el tiempo de espera tras un fallo?

Primero identifica si el cliente, un proxy o una solicitud al servicio de origen dejó de esperar. Consulta la guía de tiempos de espera y verifica el resultado con una solicitud pequeña.

Referencia de la API

Guías para desarrolladores

Errores de la API de BetterToken: códigos HTTP y límites

Antes de diagnosticar el problema

Interpreta la respuesta de error

Comprueba el estado HTTP

Reintenta los fallos temporales

Prepara la solicitud

Busca la guía para tu caso

Confirma la solución

Preguntas frecuentes

¿Todos los errores 429 requieren esperar y reintentar?

¿Debo aumentar el tiempo de espera tras un fallo?

Recursos relacionados

​Antes de diagnosticar el problema

​Interpreta la respuesta de error

​Comprueba el estado HTTP

​Reintenta los fallos temporales

​Prepara la solicitud

​Busca la guía para tu caso

​Confirma la solución

​Preguntas frecuentes

​¿Todos los errores 429 requieren esperar y reintentar?

​¿Debo aumentar el tiempo de espera tras un fallo?

​Recursos relacionados

Antes de diagnosticar el problema

Interpreta la respuesta de error

Comprueba el estado HTTP

Reintenta los fallos temporales

Prepara la solicitud

Busca la guía para tu caso

Confirma la solución

Preguntas frecuentes

¿Todos los errores 429 requieren esperar y reintentar?

¿Debo aumentar el tiempo de espera tras un fallo?

Recursos relacionados