> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CardGroup cols={2}>
  <Card title="400 - Bad Request" icon="circle-exclamation">
    Formato de solicitação inaceitável ou sintaxe incorreta. Verifique a estrutura da solicitação em relação à especificação da API.
  </Card>

  <Card title="403 - Forbidden" icon="lock">
    Problema com chave da API ou tokens de autorização ausentes. Verifique suas credenciais de autenticação.
  </Card>

  <Card title="404 - Not Found" icon="file-slash">
    Recurso não existe ou URL está incorreta. Verifique o caminho do endpoint e o ID do recurso.
  </Card>

  <Card title="422 - Unprocessable Entity" icon="file-circle-xmark">
    Corpo da solicitação não corresponde ao modelo esperado. Campos obrigatórios ausentes ou tipos de dados incorretos.
  </Card>

  <Card title="429 - Rate Limit" icon="gauge-high">
    Muitas solicitações. Verifique os cabeçalhos de limite de taxa: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
  </Card>

  <Card title="5xx - Server Error" icon="server">
    Problema inesperado do servidor. Nossa equipe normalmente corrige esses problemas rapidamente. Verifique a página de status.
  </Card>
</CardGroup>

## Códigos de Erro Específicos

<AccordionGroup>
  <Accordion title="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](/pt/api-reference/authentication) para detalhes.
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Erros de Categoria">
    * **`invalid_category`** - Apenas um de `id`, `ids` ou `disjunctions` deve ser definido, onde nenhum array seja maior que 5
  </Accordion>

  <Accordion title="Erros de Sessão">
    * **`invalid_opaque_user_id`** - Valor do ID de usuário opaco não deve ter mais de 90 caracteres
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Erros de Dispositivo">
    * **`invalid_device`** - O dispositivo deve ser um dos seguintes: `desktop` ou `mobile`
  </Accordion>

  <Accordion title="Erros de Pesquisa">
    * **`too_many_search_query_words`** - Limite de palavras de consulta de pesquisa na solicitação excedido
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="Erros de Evento de Compra">
    * **`no_purchase_items`** - Pelo menos um item deve ser comprado
    * **`missing_purchased_at`** - Campo obrigatório `purchasedAt` ausente
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Erros de Experimento">
    * **`experiment_variant_too_long`** - Variantes de experimento do marketplace têm comprimento máximo de 10 caracteres
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Erros do Servidor">
    * **`internal_server_error`** - O servidor encontrou um problema
    * **`request_canceled`** - O chamador cancelou a solicitação
  </Accordion>
</AccordionGroup>

## Problemas Comuns de Integração

<CardGroup cols={2}>
  <Card title="Eventos Não Aparecem" icon="eye-slash">
    **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`)
  </Card>

  <Card title="Resultados de Leilão Vazios" icon="rectangle-xmark">
    **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
  </Card>

  <Card title="Problemas de Atribuição" icon="link-slash">
    **Atribuição não está funcionando corretamente:**

    * Veja nosso [Guia de Solução de Problemas de Atribuição](/knowledge-base/ad-platform/reporting/attribution-troubleshooting)
    * Verifique se os IDs de lance resolvidos são passados corretamente
    * Verifique se os eventos de compra incluem os IDs de produto apropriados
  </Card>

  <Card title="Problemas de Conexão" icon="wifi-slash">
    **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
  </Card>
</CardGroup>

<Warning>
  **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.
</Warning>

## Erros de Validação Detalhados

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

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Backoff Exponencial" icon="arrows-rotate">
    Tente novamente solicitações com falha com atrasos crescentes entre tentativas:

    ```python theme={null}
    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)
    ```
  </Card>

  <Card title="Use Cabeçalhos de Limite de Taxa" icon="gauge">
    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.
  </Card>
</CardGroup>

<Note>
  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.
</Note>

## Problemas de Conexão e Rede

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

<Steps>
  <Step title="Testar Conectividade Básica">
    Verifique se você pode alcançar a API da Topsort:

    ```bash theme={null}
    curl -I https://api.topsort.com
    ```
  </Step>

  <Step title="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`
  </Step>

  <Step title="Verificar Suporte TLS">
    Certifique-se de que seu cliente HTTP suporta versões modernas de TLS:

    ```bash theme={null}
    openssl s_client -connect api.topsort.com:443
    ```
  </Step>

  <Step title="Configurar Tempos Limite">
    Defina valores de tempo limite apropriados e implemente lógica de nova tentativa:

    ```python theme={null}
    session = requests.Session()
    session.timeout = (10, 30)  # (connect, read)
    ```
  </Step>

  <Step title="Verificar Página de Status">
    Visite [topsort.statuspage.io](https://topsort.statuspage.io) para o status do serviço
  </Step>
</Steps>

### Problemas Comuns de Rede

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Ferramentas de Depuração

<CardGroup cols={2}>
  <Card title="Logs de Desenvolvedor" icon="list-check">
    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](/api-reference/logs) para ajuda na interpretação de entradas de log.
  </Card>

  <Card title="Página de Status" icon="signal">
    Monitore a saúde do serviço e manutenção planejada em [topsort.statuspage.io](https://topsort.statuspage.io)

    Assine atualizações para notificações em tempo real.
  </Card>
</CardGroup>

## Precisa de Ajuda?

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

* **Verifique a página de status:** [topsort.statuspage.io](https://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