<!-- https://www.akrus.digital/docs/erros · revisado em 2026-10-08 · gerado do mesmo conteúdo da página HTML -->
_Operação da integração · v1 em prévia_

# Códigos de erro e quando tentar novamente.

Os erros têm um envelope consistente. Use error.code na lógica da integração; a mensagem pode mudar.

> **Antes de integrar**
>
> Contrato em prévia. A implementação foi validada localmente; a liberação em produção ainda precisa ser confirmada pela equipe. O acesso programático exige plano Scale efetivo, credencial e escopos autorizados. Solicite acesso e a URL do ambiente antes de integrar.
>
> [Ver disponibilidade](https://www.akrus.digital/docs/ambientes)

## Envelope

```json
{
  "error": {
    "code": "unauthenticated",
    "message": "Credencial ausente, inválida ou revogada."
  },
  "version": "v1"
}
```

## Códigos e ações

| HTTP | Código | Como tratar |
| --- | --- | --- |
| 401 | unauthenticated | Confira a credencial e se ela foi revogada. Não repita indefinidamente. |
| 403 | forbidden_scope | Confira o plano Scale efetivo e o escopo necessário para o recurso. |
| 400 | invalid_cursor | Confira o cursor recebido da resposta anterior. |
| 400 | invalid_limit | Use um inteiro de 1 a 100. |
| 429 | rate_limited | Respeite o Retry-After em segundos antes de tentar de novo. |
| 503 | unavailable | Aguarde e tente novamente com intervalo progressivo. |
| 404 | unknown_resource | Confira o endereço e a versão do recurso. |

## Decida se vale tentar novamente

| Situação | Conduta da integração |
| --- | --- |
| 400, 401, 403 ou 404 | Corrija parâmetro, credencial, plano, escopo ou rota antes de repetir. |
| 429 | Aguarde Retry-After e coordene os processos da mesma credencial. |
| 503 ou falha temporária de rede | Use espera progressiva, teto de tentativas e possibilidade de interromper. |
| Resposta inesperada | Interrompa a interpretação dos dados e registre contexto sem segredos. |

## Registre a falha e prepare um relato técnico

### Registro de falhas

- [ ] Registre a rota, o horário, o status e o código para diagnóstico.
- [ ] Não registre o cabeçalho Authorization nem a credencial.
- [ ] Limite o número de tentativas e evite repetir erros de autenticação sem corrigir a causa.

### Relato técnico

- [ ] Método e caminho da requisição, sem o cabeçalho de autenticação.
- [ ] Ambiente autorizado, horário e fuso da ocorrência.
- [ ] Status HTTP, error.code e frequência do problema.
- [ ] Comportamento esperado e o que já foi tentado.

---

Anterior: [Paginação](https://www.akrus.digital/docs/paginacao) · Próximo: [Limites de uso](https://www.akrus.digital/docs/limites)
