# Límites de velocidad de errores

### Formato de error

Cada respuesta de error utiliza la misma forma de JSON y un código de estado HTTP adecuado:

```json
{
  "statusCode": 403,
  "code": "FORBIDDEN",
  "message": "Missing required scope: govern:checkpoints:write"
}
```

| Campo | Descripción |
| ------------ | ------------------------------------------- |
| `statusCode` | El código de estado HTTP, repetido en el cuerpo. |
| `code` | Un código de error estable y legible por máquina. |
| `message` | Una descripción legible por el ser humano, segura para conectarse. |

#### Códigos de estado

| Situación | Cuando sucede |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request` | Falta o inválido un campo requerido, por ejemplo. `action` omitido en un puesto de control, o `tool_name` omitido en un `tool_call` Escaneo. |
| `401 Unauthorized` | La clave de API está desaparecida, malformada, revocada o usada por una IP desactivada. |
| `403 Forbidden` | La clave es válida pero carece del alcance requerido. |
| `404 Not Found` | El recurso de referencia (por ejemplo, un documento de control) no existe en este espacio de trabajo. |
| `429 Too Many Requests` | Se superó el límite de tarifas. Honorable. `Retry-After` Cabeza. |
| `500` | Un error inesperado del servidor. El `message` es genérico; reingreso con retroceso. |

### Plazos de tarifas

La API impone a **corredera-ventana, por-key** límite.

* **Default:** 600 solicitudes por minuto por clave de API.
* **Respuesta cuando se exceda:** `429 Too Many Requests` con una `Retry-After` cabecera (segundos a esperar).

```
HTTP/1.1 429 Too Many Requests
Retry-After: 12
```

#### Polling etiquette

Al encuestar un punto de control con `GET /v1/checkpoints/{id}`, mantener un **mínimo de 1 segundo** entre las encuestas del mismo puesto de control, se rechaza una votación más estricta. Preferir el punto final de largo alcance `GET /v1/checkpoints/{id}/wait`, que mantiene la conexión abierta y regresa tan pronto como el estado cambia, por lo que hace mucho menos solicitudes.

### Idempotencia

Escribir puntos finales (`POST /v1/checkpoints`, `POST /v1/secure/scan`) aceptar un opcional `Idempotency-Key` encabezado por lo que las retries son seguras:

```
Idempotency-Key: 4f1e9c2a-7b3d-4a1f-9c8e-2d6b0a5f1e33
```

Reutilizando la misma llave con una **diferentes** el cuerpo de solicitud es rechazado - una clave está ligada a la carga de pago que fue visto por primera vez con. Utilice un UUID fresco por operación lógica, y reutilizarlo sólo al reintentar esa operación exacta.