# Errores y límites de frecuencia
Source: https://nordvec.com/es/docs/guides/errors-and-rate-limits

El sobre de error único que devuelve cada solicitud fallida, los encabezados de límite de frecuencia y cómo reintentar una escritura de forma segura.



Cada endpoint falla de la misma manera, por lo que un cliente maneja errores, límites de tasa y reintentos una vez y reutiliza ese código en todas partes, incluso sobre [MCP](/docs/guides/mcp).

## El sobre de error [#el-sobre-de-error]

Toda respuesta que no sea 2xx es un objeto JSON:

```json
{
  "defined": false,
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests",
  "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}
```

* `code` es el error a nivel HTTP, por ejemplo `UNAUTHORIZED`, `FORBIDDEN`,
  `NOT_FOUND`, `BAD_REQUEST` o `TOO_MANY_REQUESTS`.
* `data.reason`, cuando está presente, es una razón más precisa legible por máquina, como
  `auth.key_not_found` o `rate_limit.exceeded`. Haz branching sobre ella en lugar de sobre
  `message`, que es para personas y puede cambiar.
* `defined` es `true` cuando la operación lista ese error en la
  [referencia de la API](/docs/api), y `false` para errores que cualquier solicitud puede encontrar
  (autenticación, límites de tasa, una ruta desconocida).
* Un fallo de validación responde `BAD_REQUEST` con los problemas en
  `data.formErrors` y `data.fieldErrors`.

Toda respuesta también lleva un `X-Request-ID`. Cítalo cuando contactes con soporte,
y podremos encontrar esa solicitud exacta.

## Estados comunes [#estados-comunes]

| Estado | Código                  | Qué hacer                                                                           |
| ------ | ----------------------- | ----------------------------------------------------------------------------------- |
| `400`  | `BAD_REQUEST`           | Corrige la solicitud; `data.fieldErrors` nombra los campos                          |
| `401`  | `UNAUTHORIZED`          | Envía una clave o sesión válida                                                     |
| `403`  | `FORBIDDEN`             | La clave carece del ámbito o el rol que necesita la operación                       |
| `404`  | `NOT_FOUND`             | El recurso no existe, o no tienes permiso para verlo                                |
| `409`  | `CONFLICT`              | Una escritura duplicada aún está en curso; reintenta en breve                       |
| `413`  | `PAYLOAD_TOO_LARGE`     | El cuerpo de la solicitud supera 1 MB; divide un envío masivo en lotes más pequeños |
| `422`  | `UNPROCESSABLE_CONTENT` | La solicitud está bien formada pero no se puede aplicar                             |
| `429`  | `TOO_MANY_REQUESTS`     | Espera `Retry-After`, luego reintenta                                               |

## Límites de tasa [#límites-de-tasa]

Cada respuesta indica el límite contra el que se contó, en dos formas:

* los encabezados `X-RateLimit-*`;
* los campos estructurados IETF `RateLimit` (estado en vivo: `r` son las solicitudes
  restantes, `t` los segundos hasta que se reinicie la ventana) y `RateLimit-Policy`
  (la cuota: `q` es el límite, `w` la ventana en segundos).

Un `429` también lleva `Retry-After` en segundos y `data.retryAfterMs`. Espera al menos ese tiempo antes de la siguiente solicitud; reintentar antes se cuenta y se rechaza de nuevo.

## Reintentos de escrituras de forma segura [#reintentos-de-escrituras-de-forma-segura]

Una operación de escritura que lista un encabezado `Idempotency-Key` en la
[referencia de la API](/docs/api) se puede reintentar sin realizar el trabajo dos veces. Envía una clave por cada escritura lógica y repite la misma clave en cada reintento:

* la misma clave con el mismo cuerpo en un plazo de 24 horas reproduce la respuesta almacenada;
* la misma clave con un cuerpo diferente se rechaza con `422`;
* un duplicado que llega mientras la primera aún se está ejecutando recibe `409`.

Una operación sin el encabezado no es idempotente, así que reinténtala solo cuando sepas que el primer intento no se completó.