Saltar para o conteúdo principal

​
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:
CampoTipoDescrição
errCodestringString curta identificando exclusivamente o problema
docUrlstringLink para documentação fornecendo mais informações
messagestringExplicaçã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

  • invalid_api_key - A chave da API no cabeçalho de autorização está ausente, inválida ou expirou. Veja autenticação para detalhes.
  • 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
  • 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
  • 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
  • invalid_category - Apenas um de id, ids ou disjunctions deve ser definido, onde nenhum array seja maior que 5
  • invalid_opaque_user_id - Valor do ID de usuário opaco não deve ter mais de 90 caracteres
  • 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
  • invalid_device - O dispositivo deve ser um dos seguintes: desktop ou mobile
  • too_many_search_query_words - Limite de palavras de consulta de pesquisa na solicitação excedido
  • 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
  • no_purchase_items - Pelo menos um item deve ser comprado
  • missing_purchased_at - Campo obrigatório purchasedAt ausente
  • invalid_marketplace - Nenhum marketplace desse tipo existe
  • invalid_vendor - Nenhum fornecedor desse tipo existe
  • resource_not_found - O recurso solicitado não foi encontrado
  • experiment_variant_too_long - Variantes de experimento do marketplace têm comprimento máximo de 10 caracteres
  • no_listing_experiment_variant - Variantes de experimento do marketplace são suportadas apenas para leilões de listagem patrocinada
  • 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
  • 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
  • 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
  • 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:

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

Sintomas: Erros de validação de certificado, falhas de handshake SSLSoluçõ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
Sintomas: Conexão recusada, solicitações travadasSoluçõ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
Sintomas: Solicitações atingindo tempo limite, travando indefinidamenteSoluçõ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
Sintomas: Problemas de regiões geográficas específicasSoluçõ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.ioAssine 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