# Errores y límites de solicitudes

Los errores de la API de KolWrite usan respuestas JSON con un `code` estable
siempre que el cliente pueda actuar.

```json
{
  "detail": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the 'jobs:write' scope",
    "required_scope": "jobs:write"
  }
}
```

## Estados habituales

| Estado | Significado |
|---|---|
| `400` | Entrada no válida o combinación de opciones no admitida |
| `401` | Token ausente, no válido, caducado o revocado |
| `403` | El token es válido, pero no tiene acceso al ámbito o a la ruta |
| `404` | El recurso no existe o no es visible para el propietario del token |
| `409` | Conflicto, normalmente debido a la idempotencia o a una transición de estado |
| `422` | La estructura del cuerpo de la solicitud es JSON válido, pero no supera la validación |
| `429` | Límite de solicitudes o presión en la reserva de créditos |
| `5xx` | Error temporal del servicio de KolWrite |

## Recomendaciones de reintento

Reintenta los códigos `429`, `502`, `503` y `504` con una espera exponencial
y una variación aleatoria. Usa `Idempotency-Key` al crear trabajos para que
los reintentos de red nunca creen trabajos duplicados. No reintentes los
códigos `401` y `403` ni los errores de validación hasta haber corregido el
token o la solicitud.