API cloud
Erros e limites de taxa
Formato de erros, códigos de status e headers de limite de taxa da API cloud do zn.
Os erros retornam JSON com uma mensagem em error. Erros de cota adicionam um code legível por máquina.
{"error": "Invalid API key"}{"error": "Monthly call limit reached", "code": "MONTHLY_LIMIT_REACHED"}Códigos de status
| Status | Significado | O que fazer |
|---|---|---|
| 400 | O corpo não tem input, ou input passa de 20.000 caracteres |
Envie {"input": "..."} e divida entradas longas |
| 401 | Chave de API ausente ou inválida | Confira o header Authorization e a chave no painel |
| 429 | Limite mensal atingido (MONTHLY_LIMIT_REACHED) |
Aguarde o tempo de Retry-After, adicione créditos ou faça upgrade |
| 500 | Falha inesperada na análise | Tente de novo uma vez com espera (cada requisição conta na cota) |
Tome decisões com base no status HTTP e em code, não no texto de error, que pode mudar.
Headers de limite de taxa
RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset voltam nas respostas bem-sucedidas e nos 401 e 429, para que você possa desacelerar antes de chegar a um 429. Um 429 também inclui Retry-After.
Fail open ou fail closed?
Decida o que seu agente faz quando o zn está inacessível. Para ferramentas de alto impacto (shell, pagamentos, exclusão de dados), use fail closed: não execute a ferramenta. Para leituras de baixo impacto, você pode usar fail open e manter as regras locais do zn-gate como fallback.