Errores
Los errores de Quipua tienen siempre esta forma:
JSON
{"error": "insufficient_balance", "message": "Saldo insuficiente: recarga tu cuenta"}error: código estable, pensado para tu código (if err == "insufficient_balance").message: explicación en español para personas. Puede cambiar; no lo compares.
Si el error viene del proveedor del modelo (por ejemplo, parámetros que el modelo no admite, contenido rechazado por su política o una caída sin respaldo), Quipua te lo devuelve con su estado y su cuerpo originales, que siguen el formato de OpenAI o Anthropic ({"error": {"message": …, "type": …}}). En ese caso la respuesta sí lleva x-request-id y x-ci-model-served. Las peticiones que fallan no se cobran.
Códigos
| Estado | Código | Cuándo |
|---|---|---|
| 400 | invalid_json | El cuerpo no es un objeto JSON. |
| 400 | missing_model | Falta model. |
| 400 | model_not_chat | El modelo no es de chat (imagen, audio, embeddings…). |
| 400 | invalid_ahorro | Valor no válido en x-ci-ahorro. |
| 400 | auto_not_configured | Pediste auto y el equipo no tiene configurado el modelo automático. |
| 400 | auto_no_model | Ningún modelo permitido puede atender la petición (herramientas, imágenes o tamaño). |
| 400 | invalid_request | /v1/memory/proposals sin messages ni facts. |
| 400 | missing_file, invalid_purpose, invalid_batch_file, invalid_endpoint, invalid_completion_window, invalid_metadata, invalid_input_file, model_not_batch | API diferida. |
| 401 | missing_api_key | No se envió key. |
| 401 | invalid_api_key | Key desconocida o revocada. |
| 401 | key_expired | Key caducada (por su fecha o tras una rotación). |
| 402 | insufficient_balance | Saldo insuficiente para el máximo de la petición. Ver Saldo. |
| 403 | organization_not_active | La organización no está activa (alta pendiente o suspendida). |
| 403 | key_suspended | Key suspendida por Quipua. |
| 403 | model_not_allowed | La key no tiene permiso para ese modelo. |
| 403 | team_budget_exceeded | Se superaría el presupuesto mensual del equipo. |
| 403 | key_limit_exceeded | Se superaría el límite de gasto de la key. |
| 403 | memory_disabled | La organización no tiene activada la memoria. |
| 404 | model_not_found | Modelo inexistente o no disponible para tu organización. |
| 404 | file_not_found, batch_not_found | Fichero o lote inexistente (o de otro equipo). |
| 409 | file_in_use | El fichero es la entrada de un lote en curso. |
| 410 | file_expired | El fichero ya se borró. |
| 413 | context_too_large | La entrada supera el tope de contexto de la key. |
| 413 | file_too_large | Fichero de lote de más de 50 MB. |
| 429 | rate_limited | Límite de peticiones por minuto de la key o de la organización. |
| 429 | memory_proposals_full | Demasiadas propuestas de memoria pendientes. |
| 500 | batch_file_unreadable | No se pudo leer un fichero de lote. Contacta con soporte. |
| 502 | upstream_unavailable | No se pudo contactar con el proveedor del modelo. Reintenta. |
| 502 | distill_failed | Falló la destilación de memoria. |
| 503 | batch_unavailable | La API diferida no está disponible. |
Reintentos
- Reintenta con espera exponencial:
429,502,503y los5xxdel proveedor. - No reintentes sin cambiar algo:
400,401,402,403,404,413. - Con
model: "auto", Quipua ya reintenta por su cuenta con otro modelo del equipo ante caídas o saturación del proveedor (ver Modelo automático).