Errores

Todas las respuestas que no sean 2xx tienen la misma estructura JSON: el estándar de OpenAI. Para gestionarlas mediante código, usa error.code; para la política de reintentos, usa status_code.

Carga útil del error

{
  "error": {
    "message": "Model 'xyz-2025' is not available",
    "type": "model_not_found",
    "code": "model_not_found",
    "param": null
  }
}

Códigos de estado HTTP

Códigos de error frecuentes

authentication_error

• Olvidó establecer el encabezado Authorization: Bearer ....
• La clave de API se revocó desde /app/keys.
• La clave aún tiene un prefijo incorrecto (debe comenzar por sk-kn-).

insufficient_quota

• Saldo de la cartera demasiado bajo para esta solicitud → error.code es insufficient_balance, y el error incluye el saldo que tenía la cartera (balance_usd), el importe que reserva esta solicitud (needed_usd) y dos enlaces: topup_url abre la página de facturación con una recarga preseleccionada; auto_recharge_url la abre en la configuración de recarga automática. Ninguno de los enlaces realiza un cargo por sí mismo.
• Se alcanzó el límite mensual por clave. Se restablece al comienzo de cada mes natural (UTC). Aumente el límite en /app/keys.

{
  "error": {
    "message": "Wallet balance is too low for this request. Top up at https://kunavo.com/app/billing — or turn on auto-recharge there, and a saved card refills the wallet before requests are refused.",
    "type": "insufficient_quota",
    "code": "insufficient_balance",
    "param": null,
    "balance_usd": 0.0142,
    "needed_usd": 0.0381,
    "topup_url": "https://kunavo.com/app/billing?topup=20",
    "auto_recharge_url": "https://kunavo.com/app/billing?autorecharge=1&src=api_402"
  }
}

Deje de reintentar ante insufficient_balance, salvo que la respuesta incluya un encabezado Retry-After: este significa que ya se está cobrando a su tarjeta guardada una recarga automática y la misma solicitud debería funcionar unos segundos después.

permission_error

• La clave tiene una lista de direcciones IP permitidas y la llamada se originó desde una dirección que no está incluida. El mensaje indica la dirección que detectamos: añádala (o añada su bloque CIDR) en /app/keys, o elimine por completo la lista para permitir cualquier dirección.
• Trasladar un agente a un nuevo host, a una nueva pasarela NAT o a un portátil conectado a otra red cambia esa dirección. Una clave sin lista de direcciones permitidas nunca se rechaza de esta manera.

model_not_found

• Error tipográfico en el slug. Use /models para consultar la lista canónica.
• El modelo está deshabilitado actualmente (por una interrupción del proveedor ascendente o una revisión de precios).

upstream_error

Indica que un proveedor ascendente del modelo devolvió un error que no pudimos traducir a un código más específico. El cuerpo incluye el mensaje original. Causas frecuentes:

• Sobrecarga del proveedor.
• Rechazo por moderación de contenido (pruebe con otra instrucción).
• Restricciones de región o disponibilidad.

Estrategia de reintentos

El patrón robusto más sencillo: espera exponencial con fluctuación aleatoria solo ante errores 429 / 5xx.

import time, random
from openai import OpenAI, RateLimitError, APIError

client = OpenAI(api_key=os.environ["KUNAVO_API_KEY"], base_url="https://api.kunavo.com/v1")

def call_with_retry(call, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return call()
        except RateLimitError:
            if attempt + 1 == max_attempts: raise
            # 429: exponential backoff with jitter
            time.sleep(min(2 ** attempt, 30) + random.random())
        except APIError as e:
            if e.status_code and 500 <= e.status_code < 600 and attempt + 1 < max_attempts:
                time.sleep(min(2 ** attempt, 30) + random.random())
            else:
                raise

result = call_with_retry(lambda: client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "hi"}],
))

• Limite la espera a 30 segundos por intento y el total a 5 intentos.
• No reintente los errores 4xx (salvo 408 y 429). Hacerlo solo le hará perder tiempo.
• La generación de imágenes y vídeos no es idempotente: un reintento es una generación nueva y se factura si tiene éxito. Una llamada fallida nunca se facturó, así que reintentarla es seguro. Para vídeo, POST /v1/videos acepta un encabezado Idempotency-Key: un envío repetido con la misma clave devuelve la primera tarea.
• Para chats con efectos secundarios en su propio código, elimine duplicados mediante una clave de idempotencia en la capa de su aplicación.

Depuración desde el panel

Todas las llamadas a la API, tanto las correctas como las fallidas, están visibles en /app/usage. Haga clic en cualquier fila para abrir la página con todos los detalles de la solicitud y la respuesta:

• Código de estado HTTP devuelto al cliente.
• Código de error del proveedor ascendente (cuando corresponda).
• Latencia, IP de la solicitud y agente de usuario.
• Filtrar por estado ayuda a detectar patrones (p. ej., todos los errores 422 en un modelo específico).

Cómo informar de un incidente

Si observa errores 5xx persistentes en un modelo que debería funcionar, envíe un correo a support@kunavo.com con lo siguiente:

• El slug del modelo y un ejemplo del cuerpo de la solicitud (oculte los secretos).
• El intervalo de tiempo en que se produjeron los fallos.
• El error code + message de la respuesta.
• Si es posible, un enlace al registro de uso desde /app/usage/[id].

Tiempo de respuesta: un día hábil; más rápido si el problema urgente afecta a los ingresos.

Próximos pasos

• Cómo afecta la facturación a los errores 402 y de cuota
• Gestión de claves de API