Saltar para o conteúdo principal
Esta página descreve os erros encontrados ao usar os endpoints /auctions e /events da Topsort ou as APIs, classificados por código de status HTTP: 4xx: Problema na solicitação 5xx: Problema do serviço Topsort Ambos os erros retornam arrays JSON contendo objetos de erro com os campos: errCode, docUrl e uma mensagem opcional.
CampoTipoDescrição
errCodestringUma string curta que identifica exclusivamente o problema.
docUrlstringUm link para esta documentação que fornece mais informações sobre o erro.
messagestringOpcional. Se presente, é uma explicação legível por humanos ou detalhes sobre o erro. A string para um determinado erro pode mudar com o tempo; o código não deve analisar ou despachar com base em valores específicos deste campo.
Códigos de Erro e Significados:
CódigoDescriçãoDetalhes
400Bad RequestSolicitação inaceitável, ou seja, formato incorreto
403Forbidden/UnauthorizedProblema com a API key ou tokens ausentes
404Not FoundO servidor não pode encontrar o recurso solicitado. Ou a URL da solicitação não está em nossas rotas, ou o recurso não está disponível (ou seja, a campanha solicitada não existe)
422Unprocessable EntityIncompatibilidade entre o corpo da solicitação e o modelo, ou seja, falta uma propriedade, ou a API espera uma data mas recebeu um número
429Rate Limit ExceededLimite de taxa baseado em IP foi atingido. Este erro vem com os seguintes cabeçalhos:
- X-RateLimit-Limit: número total de solicitações permitidas para o período de tempo
- X-RateLimit-Remaining: número restante de solicitações para o período de tempo
- X-RateLimit-Reset: quando você pode fazer outra solicitação

Códigos de Erro

Código de ErroDescrição
bad_requestNão foi possível analisar a solicitação; verifique a especificação OpenAPI para o esquema correto.
empty_requestA solicitação está vazia; verifique a especificação OpenAPI para o esquema correto.
internal_server_errorProblema inesperado do servidor; nossa equipe geralmente corrige esses problemas rapidamente.
invalid_api_keyAPI key ausente, inválida ou expirada; consulte authentication para mais detalhes.
invalid_auction_idO ID do leilão não corresponde a um leilão; certifique-se de passar um ID de leilão válido na solicitação.
invalid_event_typeO tipo de evento deve ser “Impression”, “Click” ou “Purchase”.
invalid_promotion_typeTipos de promoção inválidos no campo slots.
invalid_sessionO objeto session deve conter um sessionId não vazio.
missing_aspect_ratioFalta a proporção de aspecto necessária para anúncios de banner.
missing_auctionsPelo menos um leilão deve ser especificado.
missing_contextFalta o contexto necessário; especifique uma categoria, lista de produtos ou consulta de pesquisa.
missing_placementFalta o campo placement ou placement.page necessário.
missing_product_idFalta productId.
missing_promotion_typeUm leilão deve solicitar slots para pelo menos um tipo de promoção.
missing_purchased_atFalta o campo purchasedAt necessário.
missing_sessionFalta o campo session necessário.
missing_slotsFalta o campo slots necessário.
no_productsPelo menos um produto deve ser especificado.
no_purchase_itemsPelo menos um item deve ser comprado.
purchase_item_quantity_less_or_equal_than_zeroUm item de compra tem uma quantidade menor ou igual a zero.
resolved_bid_id_not_foundO ID de lance resolvido fornecido não corresponde a um registro interno.
too_few_impressionsPelo menos uma impressão deve ser incluída.
too_few_slotsPelo menos um slot deve ser especificado em um leilão.
too_many_auctionsNo máximo 5 leilões podem ser executados em paralelo; entre em contato com seu KAM para aumentar este limite.

Tratamento de limites de taxa

Nossos endpoints - exceto ao fazer chamadas para /auctions ou /events - têm limites de taxa para prevenir abuso. Se você exceder o limite de taxa, receberá uma resposta de erro 429. Existem duas formas recomendadas de lidar com esses limites

Tentar novamente com backoff exponencial

Tentar novamente com backoff exponencial é uma técnica usada em programação para tentar novamente uma operação com intervalos crescentes entre tentativas, o que ajuda a mitigar problemas como latência de rede, falhas temporárias ou restrições de recursos. Abaixo está um exemplo de código em Python sobre como a técnica pode ser implementada.
def exponential_backoff_retry(url, max_retries=5, base_delay=1, max_delay=64, retry_on_status=429):
    retries = 0
    delay = base_delay
    while retries < max_retries:
        try:
            response = requests.get(url)
            if response.status_code == retry_on_status:
                print(f"Received status code {retry_on_status}, retrying...")
                retries += 1
                if retries < max_retries:
                    print(f"Retrying in {delay} seconds...")
                    time.sleep(delay)
                    delay = min(delay * 2, max_delay)
                else:
                    raise Exception(f"All retries exhausted for status code {retry_on_status}")
            else:
                response.raise_for_status()  # Raise an exception for HTTP errors other than the specified one
                return response.json()  # Assuming the response is JSON, adjust as needed
        except Exception as e:
            print(f"Attempt {retries + 1}/{max_retries} failed: {e}")
            retries += 1
            if retries < max_retries:
                print(f"Retrying in {delay} seconds...")
                time.sleep(delay)
                delay = min(delay * 2, max_delay)
            else:
                raise

Usar Retry-After

Use os valores nos cabeçalhos para determinar quando você pode fazer outra solicitação:
  • X-RateLimit-Limit: quantas solicitações você fez durante o período de tempo
  • X-RateLimit-Remaining: solicitações restantes durante o período de tempo
  • X-RateLimit-Reset: quando você pode fazer outra solicitação
Observe que se você tiver serviços distribuídos acessando o recurso, ainda pode obter 429, mesmo se esperou a quantidade de tempo especificada em X-RateLimit-Reset. Se você está enfrentando esse problema, você pode querer substituir esta técnica pelo Backoff exponencial ou usá-los juntos, ou seja, primeiro esperar a quantidade de tempo dada por X-RateLimit-Reset e depois recorrer a tentativas com backoff exponencial.