Limites de uso e erros
O limite de 120 requisições por minuto por chave, o cabeçalho Retry-After e o significado de cada status HTTP da API aberta.
Limite de requisições
Cada chave pode fazer 120 requisições por minuto. O limite é o mesmo para todas as chaves e todos os planos e não é configurável.
Ao passar do limite, a API responde 429 com o cabeçalho Retry-After (em segundos):
HTTP/1.1 429 Too Many RequestsRetry-After: 60Content-Type: application/json
{"detail": "Limite de requisições da chave excedido"}Tentativas com chave inválida também são limitadas, por IP: depois de 30 tentativas inválidas num minuto, o mesmo IP passa a receber 429 (Muitas tentativas inválidas) com Retry-After: 60.
Formato dos erros
O erro vem com o status HTTP e a mensagem no campo detail. Trate pelo status, não pelo texto, que pode mudar.
{ "detail": "Escopo necessário: leads:write" }Erros de validação (422) trazem em detail a lista dos campos com problema, no formato padrão do FastAPI:
{ "detail": [ { "loc": ["query", "limit"], "msg": "Input should be a valid integer", "type": "int_parsing" } ]}Códigos de status
| Status | Significado | O que fazer |
|---|---|---|
200 |
Requisição atendida | — |
400 |
Dado inválido ou ausente, ou id de outra empresa (funil, etapa, responsável, contato) | Corrija o corpo ou o parâmetro. Liste os ids antes (ex.: GET /v1/funis) e use só os da sua empresa. |
401 |
Chave ausente, inválida, expirada ou revogada (Chave de API inválida, expirada ou revogada) |
Confira o cabeçalho Authorization: Bearer … e o status da chave em Configurações → API aberta. |
403 |
Sem o escopo exigido, cargo do usuário sem permissão, IP não autorizado, empresa_id de outra empresa, rota fora da API aberta, plano sem o módulo da API ou conta bloqueada por pendência de plano ou pagamento |
Leia o detail: ele diz qual foi o motivo. Ajuste os escopos ou IPs da chave, ou regularize a conta em Configurações → Assinatura. |
404 |
Registro não existe nesta empresa | Confira o id. Registros de outras empresas também respondem 404. |
409 |
Conflito de estado (por exemplo, limite de chaves ativas ou uma proposta que já mudou de situação) | Leia a mensagem: em geral é preciso escolher outra ação. |
422 |
Corpo ou parâmetro com formato inválido | O detail traz os campos com problema. |
429 |
Limite de requisições da chave (ou de tentativas inválidas do IP) | Espere o tempo de Retry-After e tente de novo. |
5xx |
Falha temporária do servidor | Tente de novo com espera crescente. |
Retentativas
- Em
429, espere oRetry-After. - Em
5xxe em falhas de rede ou tempo esgotado, repita com espera crescente (1 s, 2 s, 4 s…) e um número máximo de tentativas. - Use tempo limite de 15 a 30 segundos no seu cliente HTTP.
- Não repita em
400,401,403,404,409e422: a mesma chamada vai falhar de novo.
// Node.js 18+: retentativa com espera crescenteasync function astrify(caminho, opcoes = {}, tentativas = 4) { for (let i = 0; ; i++) { const resp = await fetch(`https://api2.astrify.com.br${caminho}`, { ...opcoes, headers: { Authorization: `Bearer ${process.env.ASTRIFY_API_KEY}`, 'Content-Type': 'application/json', ...opcoes.headers, }, signal: AbortSignal.timeout(20000), }); const repetir = resp.status === 429 || resp.status >= 500; if (!repetir || i >= tentativas - 1) return resp; const espera = resp.status === 429 ? Number(resp.headers.get('Retry-After') || 60) : 2 ** i; await new Promise((r) => setTimeout(r, espera * 1000)); }}Evite duplicidade
A API não tem cabeçalho de idempotência. Antes de repetir um POST que falhou por tempo esgotado, consulte se o registro foi criado (por exemplo, GET /v1/leads?view=list&search=…) ou guarde o id retornado na primeira resposta.