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.
{
"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.