Diagnóstico
Para cada pergunta existe uma fonte correta. Usar a fonte errada produz uma conclusão confiante e errada — é o modo mais comum de perder dinheiro aqui.
Fonte de verdade por pergunta
| Pergunta | Fonte correta | Não responde isso |
|---|---|---|
| O arquivo existe e responde? | R2 / servidor de mídia, via GET, HEAD ou Range | Estado do catálogo no TikTok |
| A importação terminou? | /catalog/product/log/ com o feed_log_id | Nova chamada de importação |
| O catálogo está disponível para anúncios? | /catalog/get/ | Contagens da importação |
| Quantos produtos existem agora? | page_info.total_number de /catalog/product/get/ | Quantidade pedida na geração do feed |
| Quais produtos podem anunciar? | ad_creation_eligible de cada produto | Vídeo acessível por HTTP 200 |
| A revisão aprovou ou rejeitou? | audit.audit_status de cada produto | Total importado |
| A campanha ou o anúncio foi criado? | IDs confirmados e leitura dos recursos | Contador do job |
| O anúncio está entregando ou gastando? | Estado de entrega e relatórios TikTok | Resultado do lançamento |
| Chegou conversão via webhook? | Recibos e eventos do IPN e envio ao pixel | Métricas de anúncio |
Como interpretar cada sinal
| Sinal | O que pode significar | O que conferir |
|---|---|---|
| HTTP 502 no HYDR | Falha de proxy, backend ou upstream. Não é diagnóstico de produto reprovado. |
|
| HTTP 200 com code diferente de 0 | Erro de negócio ou autorização na API TikTok, apesar do transporte ter funcionado. |
|
| Importação FAILED | Arquivo ou registro rejeitado na ingestão. |
|
| Importação SUCCESS com produto processing | A ingestão terminou e a revisão continua. São fases diferentes. |
|
| Catálogo vazio | Importação pendente, sem produtos, ou catálogo errado. |
|
| Mídia HEAD 405 | O servidor ou CDN não aceita HEAD. Não comprova mídia quebrada. |
|
| Conectou, mas a BC não aparece | Snapshot, discovery ou permissão ainda não sincronizados. |
|
| Conta não aceita o país | Configuração de catálogo e segmentação são consultas diferentes. |
|
| Anúncios criados, estado sem entrega | Pode ser revisão, saldo, orçamento, catálogo ou permissão. |
|
Conferir acesso à mídia corretamente
| Sinal | Significa | Não significa |
|---|---|---|
| HTTP 200 ou 206 na mídia | O arquivo existe e responde. | Que o produto foi aprovado ou está elegível. |
| HEAD 405 | O servidor ou CDN não aceita o método HEAD. | Que a imagem está quebrada — teste GET antes de concluir. |
| Range 206 | A entrega parcial de vídeo funciona sem baixar o arquivo inteiro. | Que o TikTok já processou o vídeo. |
| Link assinado expirado | A capacidade temporária de leitura venceu. | Que o armazenamento caiu — gere uma nova leitura autorizada. |
| Worker de feed negou uma origem | A política de acesso daquele Worker recusou aquela requisição. | Que a importação assinada esteja inacessível: são caminhos independentes. |
O que não deve ser confundido
Enviar arquivo ao R2≠Criar catálogo
São operações independentes.
Gerar XML≠Produtos no TikTok
O executor ainda precisa solicitar a importação.
Importação SUCCESS≠Produtos aprovados
Confirma processamento da importação, não a revisão.
Catálogo AVAILABLE≠Todo SKU elegível
Disponibilidade do catálogo não é elegibilidade do item.
Anúncio criado≠Anúncio entregando
Criado não é aprovado, veiculando nem gastando.
Preço do produto≠Orçamento e CPA
Três valores diferentes, em entidades diferentes.
33 produtos≠33 vídeos
Um vídeo pode ser referenciado por vários produtos.
Retentativas e respostas incertas
O wrapper comum usa tentativas limitadas e espera em erros de transporte, de leitura e em rejeições de QPS. Mutações importantes passam com retentativa desligada: uma falha de transporte em POST não deve causar repetição cega de criação.
Depois de receber o feed_log_id, o fluxo passa a consultar o recibo em vez de iniciar a importação novamente. Um catálogo novo pode demorar a ficar disponível no serviço de importação, e essa rejeição específica é tratada sem assumir que o primeiro POST foi aceito.
Janela de polling
Nominalmente 90 rodadas de 10s (15 min), além do tempo das próprias chamadas. É prazo de espera do fluxo, não prazo garantido de revisão pelo TikTok. Se acabar, catálogo e feed são preservados para conferência.
Nenhum diagnóstico deve ter efeito colateral
Nenhuma rotina de conferência deve criar campanha, excluir produtos, reiniciar jobs ou reenviar feeds só para testar se um catálogo existe.
Ações de manutenção
| Ação | O que faz | Não confundir |
|---|---|---|
| Excluir criativo | Remove mídia e miniatura do armazenamento e atualiza a biblioteca. | Não é sinônimo de excluir catálogo. |
| Excluir produto | Usa catalog/product/delete e sincroniza o inventário. | Não faz parte de consulta de status. |
| Excluir catálogo | Usa catalog/delete, exige Admin confirmado e bloqueia catálogos em operação. | Exclusão em massa não é transação atômica entre catálogos. |
| Reconstruir índice | Pode apagar e recriar o índice local de catálogos. | Não é comando de diagnóstico — o indexador incremental é outro. |