Gestionar límites de frecuencia y errores del servidor

Gestiona una respuesta 429

Una solicitud limitada por frecuencia devuelve 429 Too Many Requests y detail.status con el valor rate_limit_exceeded. Lee las cabeceras de respuesta antes de reintentarlo:

• Retry-After indica la espera mínima, en segundos, para una solicitud rechazada.
• X-RateLimit-Limit indica el límite del grupo.
• X-RateLimit-Remaining indica cuántas solicitudes quedan.
• X-RateLimit-Reset indica cuándo se restablece el grupo.

Espera el tiempo de Retry-After y vuelve a intentarlo con retroceso exponencial y una variación aleatoria. Reduce las solicitudes paralelas y pon el trabajo en cola; evita enviarlo todo de golpe cuando se restablezca el intervalo.

Gestiona los errores del servidor

Para una respuesta 500, el cuerpo público contiene un error genérico y un request_id, sin detalles de la excepción interna. Una respuesta 503 puede indicar que un servicio necesario no está disponible temporalmente.

Reintenta las solicitudes de solo lectura con un número limitado de intentos y esperas. Antes de repetir una solicitud que crea, actualiza, paga o cambia otro estado, averigua si el primer intento llegó a completarse. Un tiempo de espera agotado o una respuesta 5xx no demuestran que el cambio fallara; repetirlo de inmediato puede duplicar el trabajo.

Conserva los datos de diagnóstico

Registra la fecha y hora, el método, la ruta, el estado, el cuerpo de la respuesta y el X-Request-Id. Nunca registres el valor de x-api-key. Detén los reintentos automáticos tras unos pocos intentos limitados y comunica el fallo para su revisión.