Skip to main content

​
Objetivo

No todos los errores deben tratarse igual. Esta guia separa:
  • errores que conviene corregir en origen
  • errores que admiten retry controlado
  • errores donde primero debes verificar estado antes de repetir

​
Regla general

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

​
Tabla rapida

​
Politica de retry

Para consultas sin efectos, reintenta solo en estos casos:
  • 429
  • 500
  • 502
  • 503
  • 504
  • 401 solo despues de iniciar una nueva sesion
En creación, publicación, emisión, pago y correo, verifica primero el recurso y sus efectos externos aunque recibas 500 o timeout. No reintentes automaticamente:
  • 400
  • 403
  • 404
  • 409
  • 422

​
Operaciones que NO deberias repetir a ciegas

Aunque recibas un error transitorio, verifica primero si la accion ya produjo efectos cuando la operacion:
  • crea recursos comerciales o financieros
  • cambia estado de invoices o DTE
  • registra pagos
  • emite emails o WhatsApp
  • sube archivos o evidencia de visitas
Ejemplos donde conviene leer el estado antes de repetir:
  • POST /api/v1/billing/invoices/{id}/publish
  • POST /api/v1/billing/invoices/{id}/emit-dte
  • POST /api/v1/billing/invoices/{id}/send-email
  • POST /api/v1/billing/invoices/{id}/register-payment
  • POST /api/omnichannel/send
  • POST /api/v1/visit_detail/upload/{visitDetailId}

​
Backoff recomendado

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:

​
Casos frecuentes por dominio

​
Auth y sesion

401 suele indicar:
  • token vencido
  • token mal formateado
  • falta prefijo Bearer
Accion:
  • no hay refresh: exige un nuevo POST /api/better-auth/sign-in/email

​
Portal cliente

403 puede significar:
  • el contacto no tiene rol funcional para invoices o support
  • el recurso no pertenece al clientId del token portal
Accion:
  • valida el rol funcional del contacto
  • confirma que el documento o ticket pertenece al cliente correcto

​
Billing y DTE

409 o 422 suelen aparecer cuando:
  • intentas publicar una invoice fuera de secuencia
  • intentas emitir DTE sin precondiciones cumplidas
  • registras un pago con estado o monto incompatible
Accion:
  • consulta la invoice actual
  • revisa el DTE asociado, su folio, TrackID y local_status, además de referencias y pagos
  • si local_status es SII_UPLOAD_UNCERTAIN, conserva el folio y concilia con el SII antes de repetir la emisión; no hay un endpoint público que resuelva ese caso automáticamente
  • si hay TrackID y SII_PENDING, sincroniza con POST /api/v1/dte/documents/{dteId}/sync; la ausencia de aceptación aún no autoriza una nueva emisión
  • solo repite la mutación cuando se haya comprobado que no produjo el efecto esperado
Consulta el flujo de facturas y DTE para los estados y llamadas concretas.

​
Omnichannel

Los fallos mas delicados son:
  • mensajes duplicados por retry sin control
  • assignment/reply sobre threads cerrados o reasignados
  • problemas de Microsoft/WhatsApp que terminan como 5xx o estados externos inconsistentes
Accion:
  • reconsulta thread y mensajes antes de reenviar
  • usa retries solo cuando el backend o el canal fallen de forma transitoria

​
Visitas y archivos

Errores frecuentes:
  • 404 por visitDetailId o imageId inexistente
  • 400 por archivo invalido
  • timeouts o errores de upload
Accion:
  • valida existencia de la visita antes del upload
  • si el upload falla, revisa si la imagen ya quedo asociada antes de reintentar

​
Observabilidad minima

Para cualquier integracion registra:
  • endpoint
  • metodo HTTP
  • status code
  • correlation id si existe
  • mensaje de error
  • payload resumido sin secretos
  • identificador funcional del recurso si existe: clientId, invoiceId, threadId, visitDetailId

​
Referencias