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 que identifica exclusivamente o problema
docUrlstringLink para documentação com mais informações
messagestringExplicação legível opcional (pode mudar com o tempo)

​
Códigos de Status HTTP

400 - Solicitação Incorreta

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

403 - Proibido

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

404 - Não Encontrado

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

422 - Entidade Não Processável

O corpo da solicitação não corresponde ao modelo esperado. Faltam campos obrigatórios ou tipos de dados incorretos.

429 - Limite de Taxa

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

5xx - Erro do Servidor

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

​
Códigos de Erro Específicos

invalid_api_key - Chave API ausente, inválida ou expirada. Consulte autenticação para mais detalhes.
  • bad_request - Não foi possível analisar a solicitação; verifique a especificação OpenAPI
  • empty_request - O corpo da solicitação está vazio; certifique-se de enviar dados
  • missing_auctions - Pelo menos um leilão deve ser especificado
  • too_many_auctions - Máximo de 5 leilões podem ser executados em paralelo (entre em contato com KAM para aumentar)
  • too_few_slots - Pelo menos um espaço deve ser especificado em um leilão
  • missing_slots - Falta o campo obrigatório slots
  • invalid_auction_id - O ID do leilão não corresponde a um leilão válido
  • missing_promotion_type - Deve solicitar espaços para pelo menos um tipo de promoção
  • invalid_promotion_type - Tipos de promoção inválidos no campo slots
  • missing_context - Falta o contexto obrigatório; especifique categoria, lista de produtos ou consulta de pesquisa
  • missing_placement - Falta o campo obrigatório placement ou placement.page
  • missing_session - Falta o campo obrigatório session
  • invalid_session - O objeto session deve conter um sessionId não vazio
  • invalid_event_type - O tipo de evento deve ser “Impression”, “Click” ou “Purchase”
  • too_few_impressions - Pelo menos uma impressão deve ser incluída
  • missing_slot_id - Falta o campo obrigatório slotId
  • resolved_bid_id_not_found - O ID de lance resolvido fornecido não corresponde ao registro interno
  • no_purchase_items - Pelo menos um item deve ser comprado
  • missing_purchased_at - Falta o campo obrigatório purchasedAt
  • purchase_item_quantity_less_or_equal_than_zero - A quantidade do item de compra deve ser maior que zero
  • internal_server_error - Problema inesperado do servidor; nossa equipe normalmente corrige esses rapidamente

​
Problemas Comuns de Integração

Eventos Não Aparecem

Eventos retornam 200 mas não aparecem no painel:
  • Verifique se occurredAt está nos ú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

A atribuição não está funcionando corretamente:

Problemas de Conexão

Conexão recusada ou tempo limite 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 em nível de 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. Os limites de taxa se aplicam a outros endpoints como APIs de gerenciamento de campanhas e relatórios.

​
Problemas de Conexão e Rede

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

1

Teste a Conectividade Básica

Verifique se você pode alcançar a API da Topsort:
curl -I https://api.topsort.com
2

Verifique as Regras do Firewall

Certifique-se de que o tráfego HTTPS de saída (porta 443) seja permitido e adicione à lista de permissões:
  • api.topsort.com
  • *.topsort.com
3

Verifique o Suporte TLS

Certifique-se de que seu cliente HTTP suporte versões modernas de TLS:
openssl s_client -connect api.topsort.com:443
4

Configure Tempos Limite

Defina valores de tempo limite apropriados e implemente lógica de repetição:
session = requests.Session()
session.timeout = (10, 30)  # (connect, read)
5

Consulte a 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 confie em 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 ajustes de proxy se necessário pela sua rede
  • Teste sem proxy para isolar o problema
Sintomas: Solicitações com tempo limite esgotado, travando indefinidamenteSoluções:
  • Aumente os valores de tempo limite em seu cliente HTTP
  • Implemente lógica de repetição com backoff exponencial
  • Verifique cargas de solicitação grandes que excedem os limites
  • Use pool de conexões para melhor desempenho
Sintomas: Problemas de regiões geográficas específicasSoluções:
  • Teste de diferentes locais para isolar problemas regionais
  • Use um serviço CDN ou proxy se necessário
  • Entre em contato com o suporte com os detalhes de sua localização

​
Ferramentas de Depuração

Logs de Desenvolvedor

Consulte a aba Dev Tools em sua Plataforma de Anúncios para logs detalhados de solicitação/resposta da API.Consulte nosso guia de Logs de Desenvolvedor para ajuda interpretando entradas de log.

Página de Status

Monitore a saúde do serviço e manutenção planejada em topsort.statuspage.ioInscreva-se para atualizações para notificações em tempo real.

​
Precisa de Ajuda?

Se você ainda estiver enfrentando problemas após consultar este guia:
  • Consulte a página de status: topsort.statuspage.io
  • Entre em contato com o suporte com detalhes do erro e exemplos de solicitações de API
  • Revise a documentação da API para requisitos específicos do endpoint
Last updated: