Limites, erros e boas práticas

Esta página junta o que o contrato da API diz sobre respostas e erros, o que foi conferido na produção e as regras para tratar falhas sem criar dados repetidos. O que não está aqui não foi confirmado: trate como erro qualquer resposta fora do esperado e guarde o corpo inteiro no seu registro.

Códigos de resposta

O que cada endpoint diz no contrato, além do 200 e do 401:

O formato do erro

O erro de chave foi conferido na produção. A resposta é 401, em qualquer endereço, com este corpo:

{"error": {"code": 401, "message": "No valid API key provided."}}

• error.code repete o código HTTP, e error.message explica em inglês.
• O cabeçalho Content-Type dessa resposta vem text/html; charset=UTF-8, mas o corpo é JSON. Leia o corpo como JSON sem depender do cabeçalho.
• O corpo dos outros erros (400, 402, 404) não foi conferido. Decida pelo código HTTP e guarde o corpo inteiro no seu registro para entender o caso.

Limite de uso

Planeje até 100 requisições por minuto por conta. A conta tem uma chave só, então esse total vale para todas as integrações juntas: o seu sistema, o Zapier, o Make, o n8n e o Pabbly.

• Distribua os lotes no tempo. Uma fila com uma chamada por segundo fica em 60 por minuto e deixa folga.
• O código que a API devolve quando o limite passa não foi conferido. Se vier um erro fora da tabela acima (como 429 ou um 5xx), espere e tente de novo, com espera crescente: 1 segundo, depois 2, 4, 8, até umas cinco tentativas.
• Nunca repita na hora, em laço: isso só gasta mais chamadas do limite.

Uma nova tentativa com espera crescente:

async function chamarComNovasTentativas(fazerChamada, tentativas = 5) {
  for (let i = 0; i < tentativas; i++) {
    const resposta = await fazerChamada();
    // 2xx, 4xx e o 401: a resposta é final, não adianta repetir
    if (resposta.status < 500 && resposta.status !== 429) return resposta;
    await new Promise((r) => setTimeout(r, 1000 * 2 ** i)); // 1 s, 2 s, 4 s, 8 s, 16 s
  }
  throw new Error('A API não respondeu depois de várias tentativas');
}

Use a nova tentativa automática só em consultas (GET) e em chamadas que você conferiu que não duplicam nada (veja abaixo).

Paginação

Três listas têm paginação, com offset (de onde começar) e limit (quantos trazer):

Para ler tudo, peça páginas até vir uma com menos itens que o limit:

const base = 'https://app.nextagsai.com.br/api/pipelines/4001/opportunities';
const itens = [];
for (let offset = 0; ; offset += 100) {
  const resposta = await fetch(`${base}?offset=${offset}&limit=100`, {
    headers: { 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY },
  });
  const { data } = await resposta.json();
  itens.push(...data);
  if (data.length < 100) break; // a última página veio incompleta
}
console.log(itens.length);

Estas listas não têm paginação e trazem no máximo 100 itens:

Tempo limite

• Ponha um tempo limite em toda chamada no seu cliente HTTP. Os exemplos em Python usam timeout=30 (30 segundos).
• Se uma chamada que cria ou envia algo estourar o tempo, não repita direto: a NexTags pode ter recebido e feito a operação. Confira antes, como na tabela abaixo.

Repetir sem duplicar

A regra geral: procure antes de criar. O contrato não diz se a API recusa um contato, uma etiqueta ou uma oportunidade repetidos, então quem evita a duplicata é a sua integração. Veja o caminho completo em Criar ou atualizar um contato.

Relacionados