AllyOneCRM / Erros e limites

Erros e limites

Formato dos erros da API do CRM, o que cada status significa, quando repetir a chamada e como funcionam os limites.

Formato do erro

A maioria das rotas responde erro com um único campo:

{ "error": "Contato não encontrado" }

Erros de validação de schema e erros do próprio servidor HTTP vêm no formato completo:

{ "statusCode": 400, "error": "Bad Request", "message": "email: Required; password: Required" }

Para tratar os dois: leia body.message ?? body.error. O texto é para humanos, em português — decida pela status HTTP, não pela mensagem.

Status HTTP

Status	Significa
`400`	Corpo ou parâmetro inválido.
`401`	Sem credencial, token expirado ou inválido, ou API key inválida, revogada ou de outro tenant.
`403`	Sem permissão: o papel do usuário ou o escopo da API key não cobre a ação.
`404`	Não encontrado — ou de outro tenant.
`413`	Corpo acima de 256 MB.
`429`	Rate limit ou bloqueio de login.
`500` · `502` · `503`	Erro inesperado ou indisponibilidade temporária (atualização em andamento).

Quando repetir

400, 403, 404, 413: não repita — corrija o pedido.
401: renove o token (/v1/auth/refresh) e repita uma vez.
429: espere Retry-After segundos.
5xx ou timeout: repita com backoff exponencial (1 s, 2 s, 4 s…). Em criação de recursos, envie o header Idempotency-Key (até 200 caracteres) no POST: um retry com a mesma chave e corpo devolve a resposta original com Idempotent-Replayed: true em vez de criar o recurso duas vezes. A chave vale 24 h por credencial; a mesma chave com outro corpo devolve 409. Não se aplica a /v1/auth, rotas públicas e uploads de arquivo.

Rate limit

Rota	Limite
Padrão	300 requisições / minuto — por usuário em sessão (JWT); por IP de origem com API key ou sem autenticação
Login, cadastro, recuperação de senha e 2FA	5 / 15 minutos por IP

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 41

Toda resposta traz esses cabeçalhos; o 429 traz também Retry-After. Além do limite por IP, 5 senhas erradas seguidas para o mesmo e-mail e IP bloqueiam novas tentativas por 15 minutos (429). Se vários serviços seus saem pelo mesmo IP público, eles dividem o limite — centralize as chamadas.

Tamanhos e paginação

Corpo de requisição e upload de CSV: até 256 MB.
Listas paginadas por page e pageSize (padrão 50, máximo 100); a resposta traz total e totalPages.