Developers
Criar chave de APIEntrar na plataforma

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 Requests
Retry-After: 60
Content-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 o Retry-After.
  • Em 5xx e 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, 409 e 422: a mesma chamada vai falhar de novo.
// Node.js 18+: retentativa com espera crescente
async 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.

Digite para pesquisar em toda a documentação.