Guía de integración GloopAPI
Gestión de errores
Gestiona errores y límites de reintento.
Determina si se aceptó la solicitud antes de decidir si reintentar. Las páginas de los endpoints indican los estados HTTP reales, las estructuras de error y ejemplos representativos. Los protocolos no comparten necesariamente la misma estructura JSON; una respuesta binaria correcta también puede devolver JSON en caso de fallo.
Decisiones según la respuesta
| Señal | Siguiente paso |
|---|---|
| 400 / Campo o modelo no compatible | Corrige la entrada según el esquema del endpoint y el catálogo actual; no repitas sin cambios |
| 401 / 403 | Comprueba vigencia de la clave, cuenta, IP, permisos de modelo o herramienta y cuota |
| 402 / Cuota insuficiente | Añade presupuesto o reduce el alcance de las nuevas solicitudes; recupera el registro original de las tareas existentes |
| 404 | Comprueba la identidad del recurso, la ruta y los interruptores; no deduzcas que un envío desconocido nunca se ejecutó |
| 409 | Distingue conflictos de idempotencia, tareas no preparadas, cambios de cotización y recursos referenciados; trata el error concreto |
| 410 | El recurso original se eliminó o caducó; conserva las pruebas de facturación e idempotencia y no crees otra tarea automáticamente |
| 429 / 5xx / Tiempo de espera de red agotado | Aplica espera progresiva por límites o espera la recuperación del servicio y verifica la aceptación; repetir solo es seguro con un contrato de idempotencia |
Solicitudes aceptadas y desconocidas
HTTP 202 indica aceptación o finalización pendiente. Una herramienta con HTTP 200 también puede representar una tarea fallida; lee status. Aceptar una cancelación no equivale a un estado terminal cancelado. Una respuesta en streaming HTTP 200 puede contener errores o interrumpirse de forma anormal.
Ante tiempos de espera en creación, unknown o billing_review, conserva la clave original y consulta mediante recuperación asíncrona. Reintentar el guardado y regenerar son operaciones distintas. Si caducó la fuente del archivo, reintentar el guardado también puede ser irrecuperable.
Información de diagnóstico
Registra hora, método, ruta, estado HTTP, código de error, request_id disponible, ID de tarea y clave de solicitud de negocio. Elimina los datos sensibles y no registres claves API ni URL firmadas. Diagnostica con los errores devueltos por la API y tus registros de uso.
Los reintentos automáticos deben tener límites de intentos y tiempo. Investiga las solicitudes facturables si no puedes demostrar que no fueron aceptadas; no uses envíos duplicados como recuperación predeterminada.
Códigos estables de error de herramientas
| Código | HTTP | Tratamiento seguro |
|---|---|---|
| invalid_input | 400 | Verifica version e input_schema exactos y corrige la entrada de la nueva solicitud |
| invalid_cursor | 400 | No construyas cursores; actualiza la primera página para obtener otro next_cursor |
| quote_required / budget_required | 400 | Completa la cotización o el límite de coste de la nueva llamada según los campos de capacidad |
| quote_expired / quote_stale / invalid_quote | 409 | Verifica y recotiza solo llamadas nuevas cuyo no envío esté confirmado; cotizaciones inexistentes o ajenas devuelven invalid_quote sin revelar propiedad |
| budget_exceeded | 409 | El presupuesto de la nueva llamada es insuficiente; verifica maximum_usd y elige explícitamente el presupuesto |
| idempotency_conflict | 409 | La solicitud cambió con la misma clave; recupera el cuerpo completo original y no reenvíes automáticamente con otra clave |
| tool_service_unavailable | 503 | Fallo de infraestructura o capacidad temporalmente no disponible; recupera los envíos desconocidos con identidad, clave y solicitud completa originales |
Si se desconoce el resultado de creación, consulta primero el run_id original. Sin run_id, repite con la clave de API, Idempotency-Key y solicitud de creación completa originales, incluidos quote_id y max_cost_usd. No modifiques un envío desconocido porque caduque la cotización o se desactive un interruptor. Solo una operación nueva confirmada como no aceptada puede recotizarse o usar otra clave de solicitud.