# Erros e limites de taxa

Os erros da API do KolWrite são respostas JSON com um `code` estável sempre que
o cliente pode agir.

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

## Status comuns

| Status | Significado |
|---|---|
| `400` | Entrada inválida ou combinação de opções não suportada |
| `401` | Token ausente, inválido, expirado ou revogado |
| `403` | O token é válido, mas falta escopo ou acesso à rota |
| `404` | O recurso não existe ou não é visível para o dono do token |
| `409` | Conflito, em geral de idempotência ou de mudança de estado |
| `422` | O corpo da requisição é um JSON válido, mas não passa na validação |
| `429` | Limite de taxa ou pressão na reserva de créditos |
| `5xx` | Erro temporário do serviço KolWrite |

## Orientação sobre novas tentativas

Tente de novo após `429`, `502`, `503` e `504` com espera exponencial e jitter.
Use `Idempotency-Key` ao criar tarefas para que novas tentativas por falha de rede nunca criem
tarefas duplicadas. Não tente de novo após `401`, `403` ou erros de validação até
corrigir o token ou a requisição.