Limites

A API entra com o plano pago

O período de teste não inclui chamadas da API. Você consegue criar uma chave, mas a primeira chamada volta 402:

{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "O plano desta conta não inclui chamadas da API.",
  "motivo": "plano_sem_api"
}

Esperar não resolve, e é por isso que a resposta é 402 e não 429: o que falta é o plano, não o próximo ciclo.

Limite de chamadas

Cada conta em plano pago tem um limite mensal de chamadas da API, que renova junto com o ciclo da assinatura.

O limite existe porque a API remove o único freio que o atendimento humano tinha: alguém precisar digitar. Um laço de repetição produz numa madrugada o que nenhum negócio produz numa década.

Atendimento por WhatsApp e pelo widget continua ilimitado. O limite vale apenas para chamadas da API.

Quando ele acaba:

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "O limite de chamadas da API deste ciclo foi atingido.",
  "motivo": "limite_de_chamadas"
}

Tentar de novo funciona no ciclo seguinte. Se precisar de mais antes disso, fale com a gente.

A diferença para o 402 acima importa: aqui o ciclo seguinte libera sozinho.

Assinatura

Se a assinatura da conta não estiver ativa, a resposta é 402:

{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "A assinatura desta conta não está ativa.",
  "motivo": "expired"
}

A diferença entre 429 e 402 importa na hora de tratar: no primeiro caso esperar resolve, no segundo não.

Requisições por minuto

Há também um limite de ritmo, por chave, para proteger a plataforma de picos. Ao ultrapassá-lo você recebe 429 com cabeçalhos x-ratelimit-* dizendo quanto resta e quando reinicia.

Ele é generoso para uso normal. Se estiver provisionando em lote, distribua as chamadas em vez de disparar todas de uma vez.

Tamanho

A mensagem do chat aceita até 4000 caracteres. Listagens devolvem no máximo 100 itens por página; use limite e deslocamento para paginar:

GET /v1/agents/{id}/conversations?limite=50&deslocamento=100

Erros, em resumo