# Limites, erros e boas práticas

> Os códigos de resposta da API, o formato do erro, quantas chamadas planejar por minuto, a paginação e como repetir chamadas sem duplicar contatos e envios.

Endereço: https://docs.nextags.com.br/comecar/limites-e-erros/
Tipo: Referência

Atualizado em: 26/10/2026

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

| Código | O que quer dizer |
|---|---|
| `200` | Deu certo. A resposta traz os dados pedidos ou `{"success": true}`. |
| `400` | Algum dado da chamada está errado ou faltando. |
| `401` | A chave de API não veio ou não vale. Acontece em qualquer endereço. |
| `402` | A operação não foi feita (só em duas chamadas de pedido, abaixo). |
| `404` | O item não existe na conta. |

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

| Endpoint | Código | Quando |
|---|---|---|
| [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/) | `400` | O ID do contato é inválido. |
| [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/) | `404` | O contato não existe. |
| [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/) | `400` | Parâmetros inválidos. |
| [Listar agentes de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-agentes-de-ia/) | `400` | Parâmetros inválidos. |
| [Atualizar agente de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/atualizar-agente-de-ia/) | `400` | O contrato cita o código sem descrever. |
| [Listar calendários](https://docs.nextags.com.br/referencia/agenda/listar-calendarios/) | `400` | Parâmetros inválidos. |
| [Listar disparos](https://docs.nextags.com.br/referencia/disparos/listar-disparos/) | `400` | Parâmetros inválidos. |
| [Consultar disparo](https://docs.nextags.com.br/referencia/disparos/consultar-disparo/) | `404` | O disparo não existe. |
| [Alterar pedido](https://docs.nextags.com.br/referencia/ecommerce/alterar-pedido/) | `400` | O `status` não é 6, 7, 10 nem 13. |
| [Alterar pedido](https://docs.nextags.com.br/referencia/ecommerce/alterar-pedido/) | `402` | O `status` é o mesmo que o pedido já tem. |
| [Alterar pedido](https://docs.nextags.com.br/referencia/ecommerce/alterar-pedido/) | `404` | O pedido não existe. |
| [Marcar pedido como pago](https://docs.nextags.com.br/referencia/ecommerce/marcar-pedido-como-pago/) | `400` | O `amount_received` é menor que o total do pedido. |
| [Marcar pedido como pago](https://docs.nextags.com.br/referencia/ecommerce/marcar-pedido-como-pago/) | `402` | O pagamento não foi concluído. O contrato diz que o contato recebe uma mensagem no Messenger com o motivo. |
| [Marcar pedido como pago](https://docs.nextags.com.br/referencia/ecommerce/marcar-pedido-como-pago/) | `404` | O pedido não existe. |

## O formato do erro

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

```json
{"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:

```javascript
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):

| Endpoint | Parâmetros | Padrão |
|---|---|---|
| [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/) | `offset`, `limit` | `0` e `100` |
| [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/) | `offset`, `limit` e `contact_id` (filtro) | `0` e `100` |
| [Listar comentários da oportunidade](https://docs.nextags.com.br/referencia/pipelines/listar-comentarios-da-oportunidade/) | `offset`, `limit` | `0` e `100` |

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

```javascript
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:

| Endpoint | O que vem |
|---|---|
| [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/) | Até 100 contatos, os de mudança mais recente no campo primeiro. |
| [Listar agentes de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-agentes-de-ia/) | Até 100 agentes. |
| [Listar calendários](https://docs.nextags.com.br/referencia/agenda/listar-calendarios/) | Até 100 calendários. |
| [Listar disparos](https://docs.nextags.com.br/referencia/disparos/listar-disparos/) | Até 100 disparos. |

## 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

| Tipo de chamada | Pode repetir? | Antes de repetir |
|---|---|---|
| Consultas (`GET`) | Sim. | Nada. |
| Criar contato, etiqueta, campo, oportunidade ou comentário | Só depois de conferir. | Procure o item: [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/), [Buscar etiqueta pelo nome](https://docs.nextags.com.br/referencia/etiquetas/buscar-etiqueta-pelo-nome/), [Buscar campo pelo nome](https://docs.nextags.com.br/referencia/campos-personalizados/buscar-campo-pelo-nome/), [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/) com `contact_id`, [Listar comentários da oportunidade](https://docs.nextags.com.br/referencia/pipelines/listar-comentarios-da-oportunidade/). |
| Enviar fluxo, texto, arquivo, conteúdo ou produtos | Não: o contato recebe de novo. | Registre no seu sistema o que já foi enviado e confira na conversa da **Caixa de Entrada**. |
| Reenviar disparo | Não: o Broadcast sai de novo. | [Consultar disparo](https://docs.nextags.com.br/referencia/disparos/consultar-disparo/). |
| Pôr ou tirar etiqueta, preencher ou limpar campo, mudar a etapa ou o status | Só depois de conferir. | Consulte o contato, o campo, a oportunidade ou o pedido. No pedido, repetir o mesmo `status` dá `402`. |
| Adicionar produto ao carrinho, marcar pedido como pago | Só depois de conferir. | [Consultar carrinho](https://docs.nextags.com.br/referencia/ecommerce/consultar-carrinho/) ou [Consultar pedido](https://docs.nextags.com.br/referencia/ecommerce/consultar-pedido/). |

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](https://docs.nextags.com.br/guias/criar-ou-atualizar-contato/).