# Erros e limites

Fonte: https://docs.ruralzap.com.br/guias/erros

Saiba quando corrigir a requisição, rever acesso ou tentar novamente.





## Causa e solução [#causa-e-solução]

| HTTP | Causa provável                                          | Próxima ação                                             |
| ---- | ------------------------------------------------------- | -------------------------------------------------------- |
| 400  | Data, intervalo, cursor ou filtro inválido              | Corrija conforme o contrato. Não repita a mesma entrada. |
| 401  | Chave inválida, expirada, revogada ou de outro ambiente | Confira o segredo e a origem no servidor.                |
| 403  | Escopo ou direito ao recurso indisponível               | Revise permissões, habilitação e acesso do responsável.  |
| 404  | Recurso ou filtro fora do Space                         | Confira o identificador e o Space da integração.         |
| 429  | Limite de chamadas excedido                             | Aguarde os segundos de Retry-After.                      |
| 503  | Serviço temporariamente indisponível                    | Faça tentativas limitadas com espera progressiva.        |

Erros da API pública usam `error.code`, `error.message` e `error.requestId`. Proxies podem retornar outro formato; valide o tipo da resposta antes de interpretar JSON.

## Limites por minuto [#limites-por-minuto]

| Categoria        | Integração | Space |
| ---------------- | ---------- | ----- |
| Consultas gerais | 60         | 120   |
| Relatórios       | 10         | 20    |

Chamadas também passam pela proteção geral da API. `Retry-After` é a orientação operacional no 429; não calcule um prazo assumindo que somente uma camada limita o tráfego.

Evite disparos concorrentes desnecessários. Use timeout, espera progressiva e um teto de tentativas. Não repita automaticamente erros de autenticação ou validação.

## Diagnóstico seguro [#diagnóstico-seguro]

Registre status HTTP, rota e identificador de requisição. Não registre chaves ou respostas financeiras. Envie o identificador pelo suporte disponível no produto.

Respostas financeiras usam `Cache-Control: no-store`. Armazenamento no seu sistema precisa respeitar as permissões e a política de dados da sua organização.