Basa la lógica en códigos estables, no en mensajes de texto

Las respuestas al error usan application/problem+json con un estado de HTTP y un código legible por máquina. Mapea los códigos en tu propio modelo de error tipado en el límite de acceso a los datos. Los detalles legibles por humanos son diagnósticos seguros y pueden localizarse o aclararse más adelante; nunca deben controlar el flujo de control de aplicaciones ni mostrarse como excepciones de infraestructura en bruto.

Trata el 401 como configuración o revocación

Una respuesta authentication_required significa que falta X-API-Key, que su formato no es válido o que la clave ha sido revocada. Reintentar automáticamente con la misma clave no resolverá el problema y puede generar más ruido. Detén la operación, avisa al responsable de la integración y comprueba el secreto desplegado. No uses la clave de otro cliente ni expongas la respuesta del proveedor al navegador.

HTTP 402 es un límite presupuestario

insufficient_credits es determinista e incluye costes y saldo restante. Suspender los trabajos programados, preservar la interfaz interactiva de solo lectura de los datos en caché cuando corresponda y enviar al propietario de la facturación al panel de control de desarrolladores. Un bucle de reintento muy ajustado solo genera llamadas rechazadas repetidas y oculta la acción comercial requerida.

Reintenta únicamente operaciones seguras y acotadas

Respeta Retry-After en las respuestas 429 y usa backoff exponencial con jitter ante fallos transitorios 502 del proveedor. Las solicitudes GET y el aprovisionamiento idempotente de usuarios son candidatos naturales para reintentos. No repitas a ciegas una mutación de conexión tras una respuesta ambigua; primero enumera las cuentas y comprueba si se creó el recurso.

Lleva identificadores de correlación a través de tu límite

Envía un X-Correlation-ID validado e inclúyelo en registros estructurados junto a portfolioId, la operación y la latencia. Esto une los diagnósticos sin registrar secretos. Devuelve una referencia segura en lugar de cargas del proveedor, detalles de base de datos o trazas.