/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.
| Campo | Tipo | Descrição |
|---|---|---|
| errCode | string | Uma string curta que identifica exclusivamente o problema. |
| docUrl | string | Um link para esta documentação que fornece mais informações sobre o erro. |
| message | string | Opcional. 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ódigo | Descrição | Detalhes | ||
|---|---|---|---|---|
| 400 | Bad Request | Solicitação inaceitável, ou seja, formato incorreto | ||
| 403 | Forbidden/Unauthorized | Problema com a API key ou tokens ausentes | ||
| 404 | Not Found | O 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) | ||
| 422 | Unprocessable Entity | Incompatibilidade 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 | ||
| 429 | Rate Limit Exceeded | Limite 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 Erro | Descrição |
|---|---|
| bad_request | Não foi possível analisar a solicitação; verifique a especificação OpenAPI para o esquema correto. |
| empty_request | A solicitação está vazia; verifique a especificação OpenAPI para o esquema correto. |
| internal_server_error | Problema inesperado do servidor; nossa equipe geralmente corrige esses problemas rapidamente. |
| invalid_api_key | API key ausente, inválida ou expirada; consulte authentication para mais detalhes. |
| invalid_auction_id | O 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_type | O tipo de evento deve ser “Impression”, “Click” ou “Purchase”. |
| invalid_promotion_type | Tipos de promoção inválidos no campo slots. |
| invalid_session | O objeto session deve conter um sessionId não vazio. |
| missing_aspect_ratio | Falta a proporção de aspecto necessária para anúncios de banner. |
| missing_auctions | Pelo menos um leilão deve ser especificado. |
| missing_context | Falta o contexto necessário; especifique uma categoria, lista de produtos ou consulta de pesquisa. |
| missing_placement | Falta o campo placement ou placement.page necessário. |
| missing_product_id | Falta productId. |
| missing_promotion_type | Um leilão deve solicitar slots para pelo menos um tipo de promoção. |
| missing_purchased_at | Falta o campo purchasedAt necessário. |
| missing_session | Falta o campo session necessário. |
| missing_slots | Falta o campo slots necessário. |
| no_products | Pelo menos um produto deve ser especificado. |
| no_purchase_items | Pelo menos um item deve ser comprado. |
| purchase_item_quantity_less_or_equal_than_zero | Um item de compra tem uma quantidade menor ou igual a zero. |
| resolved_bid_id_not_found | O ID de lance resolvido fornecido não corresponde a um registro interno. |
| too_few_impressions | Pelo menos uma impressão deve ser incluída. |
| too_few_slots | Pelo menos um slot deve ser especificado em um leilão. |
| too_many_auctions | No 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.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 tempoX-RateLimit-Remaining: solicitações restantes durante o período de tempoX-RateLimit-Reset: quando você pode fazer outra solicitação
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.