> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ugps.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores y reintentos

> Como interpretar respuestas fallidas, cuando reintentar y que casos exigen verificacion manual

## 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

| HTTP | Significado | Reintentar | Accion recomendada |
| - | - | - | - |
| `400` | Payload invalido | No | Corregir request |
| `401` | No autenticado o sesión expirada | Tras iniciar sesión | Obtener una nueva sesión Better Auth y repetir |
| `403` | Sin permisos, ownership o rol | No | Revisar acceso o relacion con el recurso |
| `404` | Recurso inexistente | No | Validar ID, dependencia previa o ambiente |
| `409` | Conflicto de negocio | No | Resolver duplicidad o estado |
| `422` | Regla de validacion o transicion invalida | No | Corregir payload o secuencia |
| `429` | Limite de uso | Si | Backoff exponencial |
| `500` | Error interno | Segun operación | En mutaciones financieras, consulta el estado antes del retry |
| `502/503/504` | Degradacion temporal | Segun operación | En mutaciones financieras, consulta el estado antes del retry |

## 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

```text theme={null}
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:

```json theme={null}
{
  "statusCode": 404,
  "message": "Client not found",
  "error": "Not Found"
}
```

## 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](/invoices-guide) 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

* [Autenticacion](/authentication)
* [Permisos y roles](/authorization-and-roles)
* [Convenciones de la API](/api-conventions)
* [Introduccion API](/api-reference/introduction)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.