Errores

Cuando una API de Inovacc rechaza o no puede completar una llamada, responde con un estado HTTP y un envoltorio de error JSON. Esta guía describe el envoltorio, los tipos de error, los códigos que comparten todas las API, y qué hacer para cada estado: corregir la solicitud, esperar o reintentar.

El envoltorio

Lenguaje

⋮

JSONEjemplo

JSON

1{ "error": { "message": "Human-readable explanation", "type": "validation_error", "code": "invalid_body" } }

code es sobre lo que debe bifurcar tu programa. Los códigos son parte del contrato de cada API: dentro de una ruta de versión como /v1, se pueden agregar códigos nuevos, y un código existente conserva su significado.
type agrupa los códigos en familias, útiles para el registro y el manejo general.
message es una oración fija en inglés para las personas. Nunca repite un valor de tu solicitud (como máximo el nombre de un campo rechazado) y nunca describe qué falló dentro de Inovacc. No la analices.

Algunas respuestas agregan un campo al envoltorio: un archivo rechazado lleva reason (por ejemplo executable o password_protected), y una conversión de esquema que no encaja lleva failing_documents, un conteo. Ignora los campos que no conozcas.

Dos respuestas no usan el envoltorio. En la API de IA, una ruta que no existe responde 404 {"error":"not_found"}. Un WebSocket (una transmisión de Eventos o un oyente de Datos) rechazado antes de la actualización responde un error HTTP ordinario; una vez abierto, termina con un código de cierre.

Tipos

`type`	Significa	Estado típico
`validation_error`	La solicitud está mal formada: un encabezado, un campo o un valor incumple las reglas.	400
`invalid_request_error`	La solicitud está bien formada pero no se puede atender tal como se envió: demasiado grande, un tipo de archivo no admitido, una URL que no se puede obtener.	400, 413, 415, 422
`authentication_error`	No hay credencial, o no es válida.	401
`authorization_error`, `permission_error`, `forbidden`	La credencial es válida pero no puede hacer esto.	403
`not_found_error`, `not_found`	La cosa no existe, o no se te permite saber que existe.	404, 410
`conflict_error`, `conflict`	La solicitud entra en conflicto con el estado actual: una versión, un modo, un límite de una colección.	409
`idempotency_error`	Un id de operación está en uso o se usó para otra cosa.	409
`rate_limit_error`, `rate_limited`	Demasiadas llamadas, o se agotó una asignación o un presupuesto.	429
`api_error`, `service_error`, `service_unavailable`, `internal_error`	Algo del lado de Inovacc, o una fuente a la que llamó por ti, falló.	500, 502, 503, 504

Las API de Datos, de IA y de Eventos usan las familias anteriores; la cadena exacta de type puede diferir entre API para la misma familia, así que maneja el code, y recurre al estado HTTP como respaldo.

Códigos que comparten todas las API

Estado	Código	Significado	Qué hacer
401	`missing_credentials`, `invalid_credentials`	No hay clave, o una clave que no es válida, venció o fue revocada.	Corrige la credencial; no reintentes sin cambios.
403	`forbidden`, `route_forbidden`, `key_disabled`, `capability_not_enabled`	La credencial no puede hacer esto.	Solicita el permiso, la ruta o la capacidad.
403	`origin_not_allowed`, `secret_key_in_browser`	Una llamada desde un navegador con un origen no listado, o una clave secreta en un navegador.	Lista el origen; usa una clave publicable.
400	`missing_operation_id`, `invalid_operation_id`	IA: un `POST`, `PUT` o `DELETE` sin un `X-Operation-Id` válido.	Envía de 8 a 128 letras, dígitos, `_` o `-`.
400	`invalid_body`, `unsupported_field`, `invalid_field`	El cuerpo o un parámetro no es válido para este endpoint.	Corrige la solicitud.
404	`*_not_found`	No existe, o no es tuyo.	Revisa el id.
409	`operation_in_progress`	El mismo id de operación sigue en ejecución.	Espera y luego reintenta con el mismo id.
409	`operation_id_reused`	IA: un id de operación ya usado para otro archivo en una colección.	Usa un nuevo id de operación para una nueva operación.
409	`version_conflict`	Datos: el registro cambió desde que lo leíste.	Vuelve a leerlo y luego reintenta.
413	`request_too_large`, `payload_too_large`	El cuerpo supera el límite de tamaño.	Hazlo más pequeño, o carga por partes.
429	`rate_limited`	Demasiadas solicitudes en la ventana.	Espera `Retry-After` segundos, cuando se indique.
429	`quota_exceeded`, `concurrency_limited`	IA: se agotó una asignación de tokens, costo o concurrencia.	Reduce el ritmo; pide a Inovacc que aumente la asignación.
429	`budget_exhausted`	IA: se gastó un presupuesto diario.	Espera hasta las 00:00 UTC (`Retry-After`).
502	`upstream_error`	Falló una fuente a la que se llamó por ti.	Reintenta con espera creciente.
503	`service_unavailable`	No se pudo acceder a una dependencia; no se hizo ni se adivinó nada.	Reintenta con espera creciente.
504	`timeout_error`	IA: el modelo no empezó a responder a tiempo.	Reintenta con espera creciente.

Cada página de producto lista todos los códigos que puede devolver, con lo que hay que hacer.

Política de reintentos

Estado	¿Reintentar?	Cómo
400, 401, 403, 404, 410, 413, 415, 422	No	La misma solicitud fallará de la misma manera. Corrígela primero.
409 `operation_in_progress`	Sí	Tras una breve espera, con el mismo id de operación.
409 `version_conflict`	Sí, tras volver a leer	Lee el registro, aplica tu cambio a la nueva versión, envía su `If-Match`.
409, otros códigos	No	El estado debe cambiar primero (crea la base de datos, espera los elementos, vacía la carpeta).
429 con `Retry-After`	Sí	No antes del número de segundos que indica.
429 sin `Retry-After`	Más tarde	Se agotó una asignación: espera minutos, no segundos, o auméntala.
500, 502, 503, 504	Sí	Con espera exponencial y variación aleatoria (por ejemplo 1, 2, 4, 8 segundos), unas pocas veces como máximo.
Error de red, sin respuesta	Sí	Igual que para 503.

Reintenta con seguridad. En la API de IA, reintenta una llamada que modifica con el mismo X-Operation-Id: si el primer intento sí tuvo éxito, recibes su respuesta almacenada en lugar de una segunda ejecución. En Datos, reintenta una creación con tu propio id de registro o If-None-Match: *, y una actualización con el mismo If-Match. En Eventos, reintenta una publicación con el mismo idempotency_key: regresa el event_id original con duplicate: true.

Ver también

Autenticación: credenciales e idempotencia.
Límites: los tamaños y tasas detrás de 413 y 429.
Webhooks: cómo se reintentan las entregas fallidas.