> For AI agents: the complete documentation index is available at https://developers.orbita.nexxo.tec.br/llms.txt, the full documentation bundle is available at https://developers.orbita.nexxo.tec.br/llms-full.txt.

# Erros e limites

## Trate o status antes do corpo

| Status    | Interpretação e próximo passo                                             |
| --------- | ------------------------------------------------------------------------- |
| 400       | Payload, UUID ou binding inválido; revise a requisição.                   |
| 401       | Credencial ausente, inválida, revogada ou expirada.                       |
| 403       | Organização, papel, vínculo ou política de acesso não permite a operação. |
| 404       | Recurso não encontrado nesse contexto.                                    |
| 409       | Conflito de versão ou estado, nas operações que oferecem esse controle.   |
| 422       | Validação de negócio; revise os campos indicados.                         |
| 429       | Limite de requisições atingido.                                           |
| 500 / 503 | Falha no serviço ou dependência; registre a correlação.                   |

O middleware de negócio usa campos como `error`, `statusCode` e `correlationId`. Validações podem incluir `details` com `propertyName` e `errorMessage`. Autenticação, rate limiting e binding podem produzir outro formato ou um corpo vazio. Não dependa de um único schema para todos os erros.

## Limite por token

A política pública usa uma janela fixa de um minuto, com padrão de **120 requisições por token**, configurável pelo operador. O código não define uma fila de espera. O padrão não é uma promessa de quota igual em todos os ambientes.

Ao receber `429`, reduza a taxa e espere a próxima janela. O contrato não garante o header `Retry-After`. Para leituras, use espera progressiva com variação; não repita uma criação de forma automática sem reconciliar seu resultado.

## Correlação

O backend recebe ou gera `X-Correlation-Id` e o devolve na resposta. Inclua esse identificador ao investigar uma falha. Os endpoints públicos de criação não implementam um contrato genérico de `Idempotency-Key`.
