Códigos de Error — Documentación de TokSpan

Códigos de Estado HTTP

Código	Significado	Acción
400	Solicitud Incorrecta	Revisa el cuerpo de la solicitud por JSON mal formado o campos obligatorios faltantes
401	No Autorizado	Verifica que tu clave API sea correcta y esté activa en el panel
404	URL Inválido / Endpoint No Encontrado	Revisa la ruta de la solicitud contra la referencia de la API
429	Límite de Tasa Excedido / Cuota Insuficiente	Para límites de tasa, implementa backoff exponencial con jitter. Si el error menciona cuota o saldo (p. ej. `insufficient_user_quota`), recarga en el Panel en lugar de reintentar — consulte los límites de tasa
500	Error Interno	Problema del lado de TokSpan — reintenta con backoff o contacta al soporte
502	Gateway Incorrecto	Error del proveedor upstream — la conmutación automática puede activarse
503	Servicio No Disponible / Modelo No Encontrado	Sobrecarga temporal: reintenta con backoff. Si el error incluye el código `model_not_found`, el modelo no está disponible para tu clave; verifica el nombre del modelo en el catálogo de modelos

Formato de Respuesta de Error

Los errores se devuelven con un objeto error que contiene un message legible y un identificador type. En TokSpan el type suele ser new_api_error, y los errores de saldo de cuenta llevan code: "insufficient_user_quota". Ejemplo:

json
{
  "error": {
    "message": "You can access all models, but this request exceeded your account balance. Please top up at the Dashboard.",
    "type": "new_api_error",
    "param": null,
    "code": "insufficient_user_quota"
  }
}

Leer el mensaje importa. Un 429 con mensaje de límite de tasa significa retroceder y reintentar; un 429 (o 400) con mensaje de cuota significa agregar créditos primero. Lee el mensaje antes de decidir cómo reaccionar. El texto del mensaje mostrado es ilustrativo: confía siempre en el código de estado HTTP y en el campo code.