Errores y reintentos
Reintente los fallos temporales y corrija los errores de solicitud antes de reenviar.
Si una llamada falla, guarde el estado HTTP, cuerpo del error sin datos sensibles, hora, endpoint, Model ID y cualquier identificador disponible antes de decidir si reintenta.
Errores comunes
| Resultado | Qué comprobar primero | ¿Reintentar inmediatamente? |
|---|---|---|
400 solicitud no válida | JSON, Model ID, tipos de campos y compatibilidad del modelo | No; corrija la solicitud |
401 fallo de autenticación | Clave de API, formato Bearer y estado de la credencial | No; corrija la credencial |
403 acceso restringido | Cuenta, ámbito de modelos, región o restricciones de origen | No; confirme el acceso |
404 ruta o recurso ausente | Dirección de API, endpoint, Model ID o identificador de tarea | No; revise la configuración |
429 demasiadas solicitudes | Tasa, concurrencia e indicaciones recibidas sobre límites | Reintente un número limitado de veces a menor tasa |
5xx error del servicio | Request ID y si se ejecutó la solicitud original | Reintente un número limitado de veces según el error |
| Tiempo de espera agotado o conexión interrumpida | Red, tiempo de espera del cliente y estado de la solicitud | No reintente a ciegas |
| Saldo o presupuesto insuficientes | Saldo disponible, presupuesto de la clave y protección de costos | Resuelva primero la restricción |
Tome la respuesta real de la API como referencia definitiva para cuerpos de error y códigos de estado.
Configure los reintentos
Reintente solo errores recuperables y limite los intentos y el tiempo total de espera. Siga las indicaciones explícitas de reintento de la respuesta cuando existan.
Ejemplo: reintente hasta 3 veces, espere aproximadamente 1, 2 y 4 segundos y añada un pequeño retraso aleatorio.Este es un ejemplo de estrategia de aplicación. No garantiza que un límite de plataforma termine en esos momentos. No active reintentos ilimitados a la vez en el SDK, la aplicación y la puerta de enlace.
Evite solicitudes duplicadas
Tras un tiempo de espera agotado en el cliente, revise la solicitud original en Registros de API. Para imágenes o tareas largas, compruebe el identificador existente antes de reenviar. Use un campo o cabecera de idempotencia solo cuando la interfaz lo admita expresamente.
Contacte con soporte
Facilite Request ID, hora y zona horaria, Model ID, endpoint, estado HTTP, error sin datos sensibles y pasos de diagnóstico ya realizados. Nunca envíe contraseña, código de verificación, clave de API completa ni contenido sensible ajeno al problema.