Tratamento de Erros

Guia completo de códigos de erro e solução de problemas para as APIs da Topsort

​

Erros

Ao trabalhar com as APIs da Topsort, você pode encontrar várias respostas de erro. Este guia ajuda você a entender, diagnosticar e resolver problemas comuns.

​

Formato de Resposta de Erro

As APIs da Topsort retornam erros como arrays JSON contendo objetos de erro:

Campo	Tipo	Descrição
errCode	string	String curta identificando exclusivamente o problema
docUrl	string	Link para documentação fornecendo mais informações
message	string	Explicação opcional legível por humanos (pode mudar com o tempo)

​

Códigos de Status HTTP

400 - Bad Request

Formato de solicitação inaceitável ou sintaxe incorreta. Verifique a estrutura da solicitação em relação à especificação da API.

403 - Forbidden

Problema com chave da API ou tokens de autorização ausentes. Verifique suas credenciais de autenticação.

404 - Not Found

Recurso não existe ou URL está incorreta. Verifique o caminho do endpoint e o ID do recurso.

422 - Unprocessable Entity

Corpo da solicitação não corresponde ao modelo esperado. Campos obrigatórios ausentes ou tipos de dados incorretos.

429 - Rate Limit

Muitas solicitações. Verifique os cabeçalhos de limite de taxa: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

5xx - Server Error

Problema inesperado do servidor. Nossa equipe normalmente corrige esses problemas rapidamente. Verifique a página de status.

​

Códigos de Erro Específicos

Erros de Autenticação

• invalid_api_key - A chave da API no cabeçalho de autorização está ausente, inválida ou expirou. Veja autenticação para detalhes.

Erros de Formato de Solicitação

• bad_request - A solicitação não pôde ser analisada
• invalid_json - A solicitação não é JSON válido
• empty_request - Corpo da solicitação está vazio; certifique-se de enviar dados
• request_canceled - O chamador cancelou a solicitação
• invalid_operation - A operação não é válida no estado atual

Erros de Leilão

• missing_auctions - Você deve especificar pelo menos um leilão
• too_many_auctions - No máximo 5 leilões podem ser executados em paralelo
• too_few_slots - Pelo menos um slot deve ser especificado em um leilão
• missing_slots - Campo slots obrigatório ausente
• invalid_auction_id - ID de leilão não corresponde a um leilão válido
• missing_promotion_type - Deve solicitar slots para pelo menos um tipo de promoção
• invalid_promotion_type - Tipos de promoção inválidos no campo slots

Erros de Contexto e Posicionamento

• invalid_context - Contexto inválido. Deve especificar no máximo dois de: lista de produtos, consulta de pesquisa ou categorias (para marcas patrocinadas: no máximo uma)
• invalid_placement_id - ID de posicionamento deve estar entre 1 e 8
• missing_slot_id - ID de slot obrigatório ausente para anúncios em banner

Erros de Categoria

• invalid_category - Apenas um de id, ids ou disjunctions deve ser definido, onde nenhum array seja maior que 5

Erros de Sessão

• invalid_opaque_user_id - Valor do ID de usuário opaco não deve ter mais de 90 caracteres

Erros de Produto e Catálogo

• no_products - Pelo menos um produto deve ser especificado
• no_products_or_category - Pelo menos um ID de produto ou um ID de categoria deve ser fornecido
• too_many_products - Limite de produtos na solicitação excedido
• product_info_mismatch - Arrays de informações do produto devem todos ter o mesmo comprimento
• invalid_quality_score - Pontuações de qualidade devem estar entre 0.0 e 1.0
• non_positive_price - Preço do produto deve ser positivo

Erros de Segmentação Geográfica

• invalid_geo_targeting - Segmentação geográfica inválida. Deve especificar location ou locations
• too_many_locations - No máximo 2 localizações podem ser especificadas
• invalid_location_cell - Célula de localização especificada não é uma célula H3 válida

Erros de Dispositivo

• invalid_device - O dispositivo deve ser um dos seguintes: desktop ou mobile

Erros de Pesquisa

• too_many_search_query_words - Limite de palavras de consulta de pesquisa na solicitação excedido

Erros de Rastreamento de Eventos

• invalid_event_time - Pelo menos um evento está no futuro
• invalid_resolved_bid_id - resolvedBidId inválido
• invalid_use_of_external_campaign_id - Não é possível definir tanto resolvedBidId quanto externalCampaignId

Erros de Evento de Compra

• no_purchase_items - Pelo menos um item deve ser comprado
• missing_purchased_at - Campo obrigatório purchasedAt ausente

Erros de Marketplace e Fornecedor

• invalid_marketplace - Nenhum marketplace desse tipo existe
• invalid_vendor - Nenhum fornecedor desse tipo existe
• resource_not_found - O recurso solicitado não foi encontrado

Erros de Experimento

• experiment_variant_too_long - Variantes de experimento do marketplace têm comprimento máximo de 10 caracteres

Erros de Razão e Conta

• account_unique_violation - Solicitação viola restrição única de conta do razão
• invalid_ledger_account - Conta do razão não existe
• insufficient_balance - Saldo insuficiente
• different_currencies - Ambas as contas devem ter o mesmo código de moeda
• equal_from_and_to - From e to devem ser diferentes

Erros de Filtro

• bad_request (operação de filtro) - A operação de filtro pode ser and ou or
• bad_request (atributos) - O número de atributos de filtro precisa estar entre 1 e 3
• bad_request (promoções) - O número de promoções de filtro precisa estar entre 1 e 3

Erros da API de Viagem

• invalid_travel_category - Categoria de viagem deve ser uma string não vazia se fornecida
• invalid_travel_date_range - Data de término deve ser maior que data de início
• too_many_passengers - Número de passageiros deve ser menor que dez
• invalid_traveler_type - Tipo de viajante deve ser um dos seguintes: family, group, solo, couple
• invalid_date_format - Data deve seguir o formato YYYY-MM-DD (por exemplo, 2012-05-08)
• invalid_travel_type - Tipo deve ser um dos seguintes: hotels, flights
• missing_variation_id - ID de variação ausente
• missing_flight_travel_context - Campos ausentes do contexto de viagem de voo

Erros do Servidor

• internal_server_error - O servidor encontrou um problema
• request_canceled - O chamador cancelou a solicitação

​

Problemas Comuns de Integração

Eventos Não Aparecem

Eventos retornam 200 mas não aparecem no painel:

• Verifique se occurredAt está dentro dos últimos 30 dias
• Verifique se o produto existe no catálogo
• Confirme a ortografia do tipo de evento (click, não Click)

Resultados de Leilão Vazios

Leilões não retornam vencedores:

• Verifique o orçamento da campanha (problema mais comum)
• Verifique se o saldo da conta é positivo
• Confirme que os produtos estão em estoque e ativos
• Verifique se existem campanhas ativas
• Verifique se os valores dos lances não são muito baixos

Problemas de Atribuição

Atribuição não está funcionando corretamente:

• Veja nosso Guia de Solução de Problemas de Atribuição
• Verifique se os IDs de lance resolvidos são passados corretamente
• Verifique se os eventos de compra incluem os IDs de produto apropriados

Problemas de Conexão

Conexão recusada ou tempo esgotado:

• Teste a conectividade: curl -I https://api.topsort.com
• Verifique se o firewall permite HTTPS de saída (porta 443)
• Adicione à lista de permissões os domínios *.topsort.com
• Verifique a validação do certificado TLS/SSL

O esgotamento do orçamento é a causa nº 1 de leilões vazios. Antes de depurar problemas complexos de leilão, primeiro verifique se suas campanhas têm orçamento diário suficiente e saldo de conta. Campanhas com orçamento zero não podem participar de leilões.

​

Erros de Validação Detalhados

Alguns endpoints retornam erros de validação detalhados com informações no nível do campo:

{
  "error": "validation_error",
  "message": "Invalid request body",
  "details": [
    {
      "field": "events[0].productId",
      "message": "Product 'sku_999' not found in catalog"
    },
    {
      "field": "events[0].occurredAt",
      "message": "Timestamp cannot be in the future"
    }
  ]
}

Use o array details para identificar exatamente quais campos têm problemas e o que precisa ser corrigido.

​

Limitação de Taxa

Backoff Exponencial

Tente novamente solicitações com falha com atrasos crescentes entre tentativas:

def retry_with_backoff(url, max_retries=5):
    delay = 1
    for i in range(max_retries):
        response = requests.get(url)
        if response.status_code != 429:
            return response
        time.sleep(delay)
        delay = min(delay * 2, 64)

Use Cabeçalhos de Limite de Taxa

Respeite os cabeçalhos de limite de taxa nas respostas:

• X-RateLimit-Limit - Total de solicitações permitidas
• X-RateLimit-Remaining - Solicitações restantes
• X-RateLimit-Reset - Quando o limite é redefinido

Aguarde até X-RateLimit-Reset antes de tentar novamente.

Os endpoints de Leilões (/v2/auctions) e Eventos (/v2/events) não têm limite de taxa. Limites de taxa se aplicam a outros endpoints como APIs de gerenciamento de campanha e relatórios.

​

Problemas de Conexão e Rede

​

Lista de Verificação de Solução de Problemas

1. Testar Conectividade Básica

   Verifique se você pode alcançar a API da Topsort:

   curl -I https://api.topsort.com
   
2. Verificar Regras de Firewall

   Certifique-se de que o tráfego HTTPS de saída (porta 443) é permitido e adicione à lista de permissões:

   • api.topsort.com
   • *.topsort.com
3. Verificar Suporte TLS

   Certifique-se de que seu cliente HTTP suporta versões modernas de TLS:

   openssl s_client -connect api.topsort.com:443
   
4. Configurar Tempos Limite

   Defina valores de tempo limite apropriados e implemente lógica de nova tentativa:

   session = requests.Session()
   session.timeout = (10, 30)  # (connect, read)
   
5. Verificar Página de Status

   Visite topsort.statuspage.io para o status do serviço

​

Problemas Comuns de Rede

Problemas de Certificado SSL/TLS

Sintomas: Erros de validação de certificado, falhas de handshake SSL

Soluções:

• Atualize seu cliente HTTP para suportar versões modernas de TLS
• Certifique-se de que seu sistema confia nas autoridades de certificação padrão
• Teste com: openssl s_client -connect api.topsort.com:443

Problemas de Firewall/Proxy

Sintomas: Conexão recusada, solicitações travadas

Soluções:

• Adicione à lista de permissões os domínios da Topsort (api.topsort.com, *.topsort.com)
• Permita tráfego HTTPS de saída na porta 443
• Configure configurações de proxy se necessário pela sua rede
• Teste sem proxy para isolar o problema

Problemas de Tempo Limite

Sintomas: Solicitações atingindo tempo limite, travando indefinidamente

Soluções:

• Aumente os valores de tempo limite em seu cliente HTTP
• Implemente lógica de nova tentativa com backoff exponencial
• Verifique cargas de solicitação grandes excedendo limites
• Use pooling de conexão para melhor desempenho

Conectividade Regional

Sintomas: Problemas de regiões geográficas específicas

Soluções:

• Teste de diferentes localizações para isolar problemas regionais
• Use um serviço CDN ou proxy se necessário
• Entre em contato com o suporte com os detalhes da sua localização

​

Ferramentas de Depuração

Logs de Desenvolvedor

Verifique a aba Dev Tools na sua Plataforma de Anúncios para logs detalhados de solicitação/resposta da API.

Veja nosso guia de Logs de Desenvolvedor para ajuda na interpretação de entradas de log.

Página de Status

Monitore a saúde do serviço e manutenção planejada em topsort.statuspage.io

Assine atualizações para notificações em tempo real.

​

Precisa de Ajuda?

Se você ainda estiver enfrentando problemas após consultar este guia:

• Verifique a página de status: topsort.statuspage.io
• Entre em contato com o suporte com detalhes do erro e exemplos de solicitação de API
• Revise a documentação da API para requisitos específicos do endpoint