Skip to main content

​
Objetivo

No todos los errores deben tratarse igual. Esta guia define que errores reintentar y cuales corregir en origen.

​
Regla general

  • 4xx: el problema suele estar en request, permisos o estado de negocio
  • 5xx: el problema suele estar en el backend o dependencia externa

​
Tabla rapida

HTTPSignificadoReintentarAccion recomendada
400Payload invalidoNoCorregir request
401No autenticado o token expiradoUna vezIntentar refresh y repetir
403Sin permisos o recurso bloqueadoNoRevisar rol, estado o policy
404Recurso inexistenteNoValidar ID o dependencia previa
409Conflicto de negocioNoResolver duplicidad o estado
422Regla de validacionNoCorregir datos
429Limite de usoSiBackoff exponencial
500Error internoSiRetry con backoff y observabilidad
502/503/504Degradacion temporalSiRetry controlado

​
Politica de retry

Reintenta solo en estos casos:
  • 429
  • 500
  • 502
  • 503
  • 504
  • 401 solo despues de renovar token
No reintentes automaticamente:
  • 400
  • 403
  • 404
  • 409
  • 422

​
Backoff recomendado

intento 1: inmediato
intento 2: +1s
intento 3: +3s
intento 4: +7s
Maximo recomendado:
  • 3 a 4 intentos

​
Payload de error

El shape puede variar segun modulo o stack legacy. Usa esta heuristica:
  • leer statusCode
  • leer message
  • leer error si existe
Ejemplo tipico: 
{
  "statusCode": 404,
  "message": "Client not found",
  "error": "Not Found"
}

​
Casos frecuentes

​
401 tras login exitoso

  • token vencido
  • token mal formateado
  • falta prefijo Bearer

​
409 al crear

  • cliente ya existe por RUT
  • recurso duplicado
  • regla de unicidad incumplida

​
404 en rutas encadenadas

  • se creo el recurso padre en otro ambiente
  • se uso una ruta legacy con ID distinto al esperado
  • el recurso fue transferido o eliminado

​
Observabilidad minima

Para cualquier integracion registra:
  • endpoint
  • metodo HTTP
  • status code
  • correlation id si existe
  • mensaje de error
  • payload resumido sin secretos

​
Referencias