Paginação, limites e tentativas seguras

Paginação por cursor#

Nas operações que aceitam cursor, a resposta contém data e next_cursor na raiz, não dentro de page:

json

{
  "data": [],
  "next_cursor": null
}

Comece sem cursor: GET /v1/contacts?limit=50.
Se next_cursor vier preenchido, envie esse valor no parâmetro cursor, codificado para URL, mantendo os demais filtros.
Termine quando next_cursor for null. Não existe campo has_more.
limit: de 1 a 100, padrão 50 nas listas paginadas. Não aumente além de 100.
Trate o cursor como texto opaco: não monte, modifique nem reutilize em outro recurso ou filtro.
A lista não fornece total nem representa uma fotografia imutável dos dados. Para sincronizar, deduplique por id e acompanhe alterações.

Nem todo GET é paginado. Etapas, tags, serviços, templates e regras têm contratos próprios na referência. Retornos são uma exceção: padrão 25 e next_cursor_data: null, sem continuação completa garantida. Veja Retornos.

O histórico de anúncios em GET /v1/contacts/{contact_id}/ad-attributions segue essas regras e acrescenta contact_created_at em cada página. Os eventos vêm em ordem cronológica crescente, por attributed_at e id. Veja datas e limitações do histórico.

Limites de chamadas#

Cada API Key compartilha sua cota entre REST e MCP:

Uso	Limite por minuto
Consultas REST e operações de descoberta MCP	120 por chave
Mutações REST/MCP	30 por chave
Gestão de chaves no painel	10 por usuário

Ao atingir a cota, aguarde o número de segundos de Retry-After. A API também informa X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (instante de reinício em segundos Unix). Bloqueios anteriores à API podem ter outro formato; veja Erros.

Idempotência: evitar ações duplicadas#

Toda mutação REST (POST, PATCH, PUT, DELETE) exige Idempotency-Key. No MCP, informe idempotency_key nos argumentos da ferramenta.

http

Idempotency-Key: 018ca60c-c07d-4fab-9553-6ef9d9a38f15

Gere uma chave para cada operação lógica, antes da primeira chamada, e guarde-a com o método, caminho e corpo. O valor aceita de 8 a 128 caracteres: letras, números, ponto, sublinhado, dois-pontos e hífen.

Mesma chave, credencial, método, caminho e conteúdo: devolve o status e recibo armazenados, sem repetir a ação.
Mesma chave com conteúdo diferente: 409 idempotency_conflict.
Operação ainda em andamento: 409 idempotency_in_progress. Aguarde; não troque a chave.
Chave ausente/inválida: 400 invalid_idempotency_key.
Janela de proteção: 24 horas. Depois disso, repetir pode executar uma nova ação.

O recibo pode ser de sucesso ou erro. Se houver timeout, falha de rede ou 5xx, não conclua que nada foi gravado. Faça poucas tentativas espaçadas, com a mesma chave e o mesmo corpo. Se a resposta continuar incerta, reconcilie com uma consulta e revisão humana. Nunca troque a chave automaticamente para forçar uma venda ou envio.

Concorrência: evitar sobrescrever alterações#

Quando a operação exigir expected_updated_at:

Consulte o recurso e obtenha seu updated_at.
Envie esse valor sem alterações junto à mutação.
Se receber 409 version_conflict, consulte novamente e reconcilie a mudança antes de tentar.

Uma alteração reconciliada é uma nova operação lógica e recebe uma nova chave de idempotência. Não altere o corpo de uma tentativa cujo resultado ainda é desconhecido. Consultar apenas a versão mais recente e sobrescrevê-la sem revisão pode apagar trabalho de outra pessoa.

Limites de dados#

Corpo JSON: até 256 KiB em REST e MCP; gestão de chaves: 32 KiB.
Nome do contato: até 160 caracteres; notes: até 10.000. Outros recursos têm limites próprios.
Datas: ISO 8601 com fuso, por exemplo 2026-08-30T12:00:00Z ou 2026-08-30T09:00:00-03:00.
Dinheiro: string decimal, como "1250.00", sem R$, vírgula ou separador de milhar.
Envie somente os campos documentados. Campos desconhecidos e identificadores de clínica são rejeitados.

Identificar uma chamada#

As respostas da API incluem X-Request-Id e Cache-Control: no-store. Você pode enviar um UUID válido em X-Request-Id ou deixar o serviço gerar. Para suporte, guarde esse identificador, horário, método e rota sem parâmetros pessoais, nunca a chave ou o corpo com dados do contato.