Solução de problemas

Checklist inicial

1. Confirme que o host pertence à instância correta e usa HTTPS.
2. Confirme a versão do backend com o administrador; a documentação hospedada não prova que todo ambiente executa o mesmo commit.
3. Envie Content-Type: application/json e um objeto JSON, mesmo quando vazio.
4. Verifique o nome exato do método e seu escopo.
5. Redija o token antes de compartilhar qualquer evidência.

HTTP 400 / validação de entrada

Revise parâmetros obrigatórios e tipos. O código não é sempre BAD_REQUEST: pipelines.get usa PIPELINE_ID_REQUIRED e marketing.funnel também pode retornar INVALID_DATE_RANGE ou PIPELINE_NOT_FOUND. Casos comuns:

• messages.list exige conversation_id UUID; before, quando enviado, deve ser o cursor opaco retornado pelo servidor (até 2048 caracteres) ou o UUID legado de uma mensagem da mesma conversa. Cursor malformado ou adulterado retorna BAD_REQUEST;
• pipelines.get e tasks.get exigem id numérico;
• stages.list exige pipeline_id;
• products.get exige codigo ou sku;
• marketing.funnel exige from, to e pipeline_id.

shop.frete.calcular espera cep e itens, mas uma entrada sem cotação pode retornar HTTP 200 com motivo:cep_invalido ou motivo:sem_itens. shop.desconto.validar também usa respostas de negócio com HTTP 200 e recusa. Não espere que toda entrada incompleta desses métodos vire HTTP 400.

HTTP 401

INVALID_TOKEN indica que o valor enviado não é reconhecido pelo ambiente, inclusive quando o registro foi excluído. Token desativado é HTTP 403, não 401. Se o segmento do token estiver ausente, a URL pode nem corresponder à rota e retornar 404. Não envie o token a suporte em texto. Informe somente horário, host, método, status e um request ID sanitizado, se existir.

HTTP 403

Verifique TOKEN_DISABLED (token desativado), IP_BLOCKED (IP fora da lista autorizada), SCOPE_DENIED (escopo insuficiente) e NO_COMPANY (token sem empresa no dispatcher da revisão 8319cf51). Alguns contratos de método também documentam TOKEN_NO_COMPANY. Ter acesso na interface do aplicativo não concede automaticamente acesso pela API por token.

HTTP 404

Pode significar rota ausente no runtime, host incorreto ou versão ainda não implantada. Em métodos como pipelines.get e tasks.get, um registro não encontrado pode ser representado por HTTP 200 com result.found:false; não transforme isso automaticamente em falha de transporte.

Em messages.list, a revisão 8319cf51 retorna 404 NOT_FOUND quando a conversa não existe/não pertence à empresa do token ou quando a mensagem-âncora do cursor não está no histórico consultado. Não trate esse caso como página vazia nem tente contornar o isolamento com outro token; confirme a empresa, a conversa e a versão autorizadas.

HTTP 429 / RATE_LIMITED

A cota padrão documentada é 60 requisições por minuto por token, configurável pelo administrador. Há também limite global em /api/. Aguarde pelo menos 60 segundos quando a cota do token for excedida, respeite Retry-After quando presente e adicione jitter no consumidor. Não conclua que cabeçalhos globais representam o saldo individual do token.

Timeout ou HTTP 5xx

• Preserve um identificador local da operação e o horário.
• Não exponha a URL completa.
• Para consultas, repita com backoff limitado.
• Não existe contrato geral de Idempotency-Key. Antes de repetir qualquer escrita fora deste perfil público, consulte o estado e siga o runbook específico.

Os SDKs candidatos deste repositório não repetem chamadas automaticamente.

Envelope inesperado

Sucesso documentado:

{
  "ok": true,
  "method": "products.list",
  "result": {}
}

Valide ok, method e a presença de result. Os schemas públicos de resultado ainda são parciais; aceite campos adicionais, mas não ignore ausência de campos essenciais à sua integração.

Paginação

Não existe paginação uniforme:

• catálogo: offset/limit e next_cursor, quando presente;
• leads.list: page/limit e total real;
• tasks.list: page/limit, porém total representa o lote na revisão documentada;
• messages.list: limit (padrão 50, máximo 200) e cursor opaco em before; o retorno inclui total (tamanho do lote), total_count (histórico não excluído da conversa), hasMore e next_cursor. Reenvie next_cursor em before sem converter em número, decodificar ou reconstruir seu conteúdo. Encerre com hasMore:false e next_cursor:null; combinação incoerente deve interromper a paginação e ser diagnosticada.

Não aplique o modelo de um método a outro. A paginação de mensagens depende da revisão 8319cf51 no backend; confirme a versão antes de depender desses campos.