# Manejo de errores

> La forma de los errores de la API de watsi, cada código que puede devolver con su estado HTTP, y cuándo y cómo reintentar una solicitud sin duplicar nada.

Source: https://docs.watsi.ai/error-handling

Todo error de la API tiene la misma forma, sea cual sea la ruta:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "At least one of phone_number, wa_id, or email is required to create a contact."
  }
}
```

- `code` es estable: decide con él, nunca con `message`.
- `message` es para una persona (en inglés) y puede cambiar de redacción.
- `details` aparece sólo en algunos errores; en una validación trae la lista de campos que fallaron.

Cada respuesta, buena o mala, trae `X-Request-Id`. Regístralo: es lo que soporte necesita para encontrar tu solicitud.

## Códigos

| Estado | `code`                   | Cuándo pasa                                                                                                                                                       | ¿Reintentar?                                               |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| 400    | `FST_ERR_VALIDATION`     | Un parámetro de la query string no cumple el esquema (por ejemplo `limit=500`). El `message` dice cuál                                                            | No: corrige la solicitud                                   |
| 400    | `VALIDATION_ERROR`       | El cuerpo JSON no cumple el esquema, o una regla de la acción (como crear un contacto sin teléfono, `wa_id` ni correo). `details.errors` lista `path` y `message` | No: corrige la solicitud                                   |
| 401    | `UNAUTHORIZED`           | Falta el encabezado `Authorization`, o la clave no existe, se revocó o venció                                                                                     | No: revisa la clave                                        |
| 403    | `FORBIDDEN`              | La clave no tiene el alcance que la ruta exige                                                                                                                    | No: usa una clave con ese alcance                          |
| 404    | `NOT_FOUND`              | La ruta no existe, o lo que pediste no existe en tu espacio de trabajo                                                                                            | No                                                         |
| 409    | `IDEMPOTENCY_KEY_REUSED` | Reusaste un `Idempotency-Key` con otro cuerpo                                                                                                                     | No: usa una clave nueva ([idempotencia](/api/idempotency)) |
| 429    | `RATE_LIMITED`           | Pasaste el límite por clave o por IP                                                                                                                              | Sí, después de `Retry-After`                               |
| 500    | `INTERNAL_ERROR`         | Algo falló de nuestro lado                                                                                                                                        | Sí, con espera creciente                                   |
| 503    | `SERVICE_UNAVAILABLE`    | Una dependencia no respondió (por ejemplo, el contador del límite de tasa)                                                                                        | Sí, con espera creciente                                   |

Un `404` en una ruta que sí existe en [la lista de rutas](/api/overview#todas-las-rutas) casi siempre es un id de otro espacio de trabajo o un id mal copiado: la clave sólo ve su propio espacio de trabajo.

## Cuándo reintentar

Reintenta sólo `429`, `500`, `503` y los errores de red (sin respuesta o tiempo agotado). Un `4xx` distinto de `429` vuelve a fallar igual.

- **`429`**: espera los segundos de `Retry-After`, o hasta `X-RateLimit-Reset`. Reintentar antes sólo gasta la siguiente ventana.
- **`5xx` y errores de red**: espera creciente con algo de azar (1 s, 2 s, 4 s… hasta unos 30 s) y un máximo de 5 intentos.
- **Escrituras**: si una escritura falló sin respuesta, no sabes si se aplicó. Reintenta con el **mismo** `Idempotency-Key`: si la primera sí se aplicó, recibes su resultado en vez de escribir dos veces. Ve [Idempotencia](/api/idempotency).

```javascript Node.js
async function watsi(path, { method = 'GET', body, idempotencyKey } = {}) {
  const headers = { Authorization: `Bearer ${process.env.WATSI_API_KEY}` }
  if (body) headers['Content-Type'] = 'application/json'
  if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey

  for (let attempt = 0; attempt < 5; attempt++) {
    let res
    try {
      res = await fetch(`https://api.watsi.ai/v1/actions/${path}`, {
        method,
        headers,
        body: body ? JSON.stringify(body) : undefined,
      })
    } catch {
      await sleep(backoff(attempt)) // error de red: reintenta con la misma clave
      continue
    }
    if (res.ok) return res.json()
    if (res.status === 429) {
      await sleep(Number(res.headers.get('retry-after') ?? 60) * 1000)
      continue
    }
    if (res.status >= 500) {
      await sleep(backoff(attempt))
      continue
    }
    // Otro 4xx: reintentar no lo arregla.
    const { error } = await res.json()
    throw new Error(`${error.code}: ${error.message} (${res.headers.get('x-request-id')})`)
  }
  throw new Error('watsi: se agotaron los reintentos')
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
const backoff = (n) => Math.min(30_000, 1000 * 2 ** n) * (0.5 + Math.random() / 2)
```

> **Tip**

Genera el `Idempotency-Key` **una vez por operación**, antes del primer intento, y reúsalo en cada reintento. Una clave nueva por intento no protege de nada.
