Errores y reintentos
Lea el estado HTTP y el cuerpo del error JSON conjuntamente. Conserve cualquier identificador de solicitud o de referencia devuelto por el servicio; esto permite al soporte técnico encontrar el registro correspondiente sin recibir el prompt o la clave completa.
Códigos de estado
| Código | Significado | Acción |
|---|---|---|
400 | JSON, campo o parámetro no válido, o solicitud rechazada | Corrija la solicitud; no la reintente sin cambios |
401 | Clave ausente, no válida, caducada o revocada | Verifique Authorization: Bearer <key> y el entorno previsto |
402 | El saldo de la clave no cubre el precio del trabajo (inteligencia de empresa, vídeo) | Recargue el saldo y vuelva a enviar la solicitud |
403 | La cuenta o la clave no pueden usar el producto o la ruta solicitados | Verifique GET /v1/models y los productos habilitados de la cuenta |
404 | Ruta incorrecta o recurso no disponible | Verifique la documentación actual y el identificador |
413 | El cuerpo de la solicitud es demasiado grande | Reduzca o divida la entrada |
422 | Una ruta compatible rechazó la estructura enviada | Lea los problemas y corrija el cuerpo |
429 | Se alcanzó un límite de solicitudes, de capacidad o de la cuenta, o se agotó el presupuesto de la clave | Espere y reintente con un retardo creciente; si se agotó el presupuesto, recargue primero |
500, 502, 503 | Problema temporal del lado del servicio | Reintente un número limitado de veces, luego contacte al soporte técnico |
La API de trabajos de imagen (/api/v1/jobs/*) es la excepción: responde con el estado HTTP 200 y pone el código en el cuerpo, {"code": 422, "msg": "…", "data": null}. Consulte Generación de imágenes.
Política de reintentos
Reintente solo las respuestas 429, las 5xx temporales y los fallos de red transitorios. Use un número máximo de intentos bajo, un tiempo de espera total, retardos crecientes como 1, 2 y 4 segundos, y una pequeña variación aleatoria cuando muchos workers puedan reintentar a la vez.
No reintente una solicitud 400, 401, 402, 403, 404, 413 o 422 sin cambios. Una conexión interrumpida requiere cuidado: la solicitud puede haberse completado y consumido crédito, por lo que un duplicado automático puede generar trabajo y coste adicionales.
Qué registrar
Registre la hora aproximada y la zona horaria, el modelo público, la ruta, el estado, el identificador de solicitud o de referencia, y el alias, prefijo o los cuatro caracteres finales de la clave. Nunca registre ni envíe la clave completa, contraseñas, prompts confidenciales, trazas de la pila (stack traces) o nombres internos.
Si un reintento limitado sigue fallando, contacte a support@omev.be con un ejemplo saneado y los identificadores registrados.