> ## 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.

# Gestion des Erreurs

> Guide complet des codes d'erreur et du dépannage pour les APIs de Topsort

# Erreurs

Lorsque vous travaillez avec les APIs de Topsort, vous pouvez rencontrer diverses réponses d'erreur. Ce guide vous aide à comprendre, diagnostiquer et résoudre les problèmes courants.

## Format de Réponse d'Erreur

Les APIs de Topsort renvoient des erreurs sous forme de tableaux JSON contenant des objets d'erreur :

| Champ     | Type   | Description                                                              |
| :-------- | :----- | :----------------------------------------------------------------------- |
| `errCode` | string | Chaîne courte identifiant uniquement le problème                         |
| `docUrl`  | string | Lien vers la documentation fournissant plus d'informations               |
| `message` | string | Explication facultative lisible par l'homme (peut changer avec le temps) |

## Codes de Statut HTTP

<CardGroup cols={2}>
  <Card title="400 - Bad Request" icon="circle-exclamation">
    Format de requête inacceptable ou syntaxe incorrecte. Vérifiez la structure de la requête par rapport aux spécifications de l'API.
  </Card>

  <Card title="403 - Forbidden" icon="lock">
    Problème de clé API ou jetons d'autorisation manquants. Vérifiez vos identifiants d'authentification.
  </Card>

  <Card title="404 - Not Found" icon="file-slash">
    La ressource n'existe pas ou l'URL est incorrecte. Vérifiez le chemin du point de terminaison et l'ID de la ressource.
  </Card>

  <Card title="422 - Unprocessable Entity" icon="file-circle-xmark">
    Le corps de la requête ne correspond pas au modèle attendu. Champs requis manquants ou types de données incorrects.
  </Card>

  <Card title="429 - Rate Limit" icon="gauge-high">
    Trop de requêtes. Vérifiez les en-têtes de limite de taux : `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
  </Card>

  <Card title="5xx - Server Error" icon="server">
    Problème de serveur inattendu. Notre équipe résout généralement ces problèmes rapidement. Consultez la page de statut.
  </Card>
</CardGroup>

## Codes d'Erreur Spécifiques

<AccordionGroup>
  <Accordion title="Erreurs d'Authentification">
    * **`invalid_api_key`** - La clé API dans l'en-tête d'autorisation est manquante, invalide ou a expiré. Voir [authentification](/fr/api-reference/authentication) pour plus de détails.
  </Accordion>

  <Accordion title="Erreurs de Format de Requête">
    * **`bad_request`** - La requête n'a pas pu être analysée
    * **`invalid_json`** - La requête n'est pas un JSON valide
    * **`empty_request`** - Le corps de la requête est vide ; assurez-vous d'envoyer des données
    * **`request_canceled`** - L'appelant a annulé la requête
    * **`invalid_operation`** - L'opération n'est pas valide dans l'état actuel
  </Accordion>

  <Accordion title="Erreurs d'Enchères">
    * **`missing_auctions`** - Vous devez spécifier au moins une enchère
    * **`too_many_auctions`** - Au maximum 5 enchères peuvent être exécutées en parallèle
    * **`too_few_slots`** - Au moins un emplacement doit être spécifié dans une enchère
    * **`missing_slots`** - Champ slots requis manquant
    * **`invalid_auction_id`** - L'ID d'enchère ne correspond pas à une enchère valide
    * **`missing_promotion_type`** - Doit demander des emplacements pour au moins un type de promotion
    * **`invalid_promotion_type`** - Types de promotion invalides dans le champ slots
  </Accordion>

  <Accordion title="Erreurs de Contexte et Placement">
    * **`invalid_context`** - Contexte invalide. Doit spécifier au maximum deux parmi : liste de produits, requête de recherche ou catégories (pour les marques sponsorisées : au maximum une)
    * **`invalid_placement_id`** - L'ID de placement doit être entre 1 et 8
    * **`missing_slot_id`** - ID d'emplacement requis manquant pour les annonces bannières
  </Accordion>

  <Accordion title="Erreurs de Catégorie">
    * **`invalid_category`** - Un seul parmi `id`, `ids` ou `disjunctions` doit être défini, où aucun tableau n'est plus long que 5
  </Accordion>

  <Accordion title="Erreurs de Session">
    * **`invalid_opaque_user_id`** - La valeur de l'ID utilisateur opaque ne doit pas dépasser 90 caractères
  </Accordion>

  <Accordion title="Erreurs de Produit et Catalogue">
    * **`no_products`** - Au moins un produit doit être spécifié
    * **`no_products_or_category`** - Au moins un ID de produit ou un ID de catégorie doit être fourni
    * **`too_many_products`** - Limite de produits dans la requête dépassée
    * **`product_info_mismatch`** - Les tableaux d'informations sur les produits doivent tous avoir la même longueur
    * **`invalid_quality_score`** - Les scores de qualité doivent être entre 0.0 et 1.0
    * **`non_positive_price`** - Le prix du produit doit être positif
  </Accordion>

  <Accordion title="Erreurs de Ciblage Géographique">
    * **`invalid_geo_targeting`** - Ciblage géographique invalide. Doit spécifier soit `location` soit `locations`
    * **`too_many_locations`** - Au maximum 2 emplacements peuvent être spécifiés
    * **`invalid_location_cell`** - La cellule de localisation spécifiée n'est pas une cellule H3 valide
  </Accordion>

  <Accordion title="Erreurs d'Appareil">
    * **`invalid_device`** - L'appareil doit être l'un des suivants : `desktop` ou `mobile`
  </Accordion>

  <Accordion title="Erreurs de Recherche">
    * **`too_many_search_query_words`** - Limite de mots de requête de recherche dans la requête dépassée
  </Accordion>

  <Accordion title="Erreurs de Suivi d'Événements">
    * **`invalid_event_time`** - Au moins un événement est dans le futur
    * **`invalid_resolved_bid_id`** - resolvedBidId invalide
    * **`invalid_use_of_external_campaign_id`** - Impossible de définir à la fois `resolvedBidId` et `externalCampaignId`
  </Accordion>

  <Accordion title="Erreurs d'Événement d'Achat">
    * **`no_purchase_items`** - Au moins un article doit être acheté
    * **`missing_purchased_at`** - Champ requis `purchasedAt` manquant
  </Accordion>

  <Accordion title="Erreurs de Marketplace et Vendeur">
    * **`invalid_marketplace`** - Aucun tel marketplace n'existe
    * **`invalid_vendor`** - Aucun tel vendeur n'existe
    * **`resource_not_found`** - La ressource demandée n'a pas été trouvée
  </Accordion>

  <Accordion title="Erreurs d'Expérimentation">
    * **`experiment_variant_too_long`** - Les variantes d'expérimentation de marketplace ont une longueur maximale de 10 caractères
  </Accordion>

  <Accordion title="Erreurs de Grand Livre et Compte">
    * **`account_unique_violation`** - La requête viole la contrainte unique du compte de grand livre
    * **`invalid_ledger_account`** - Le compte de grand livre n'existe pas
    * **`insufficient_balance`** - Solde insuffisant
    * **`different_currencies`** - Les deux comptes doivent avoir le même code de devise
    * **`equal_from_and_to`** - From et to doivent être différents
  </Accordion>

  <Accordion title="Erreurs de Filtre">
    * **`bad_request`** (opération de filtre) - L'opération de filtre peut être `and` ou `or`
    * **`bad_request`** (attributs) - Le nombre d'attributs de filtre doit être entre 1 et 3
    * **`bad_request`** (promotions) - Le nombre de promotions de filtre doit être entre 1 et 3
  </Accordion>

  <Accordion title="Erreurs de l'API Voyage">
    * **`invalid_travel_category`** - La catégorie de voyage doit être une chaîne non vide si fournie
    * **`invalid_travel_date_range`** - La date de fin doit être supérieure à la date de début
    * **`too_many_passengers`** - Le nombre de passagers doit être inférieur à dix
    * **`invalid_traveler_type`** - Le type de voyageur doit être l'un des suivants : `family`, `group`, `solo`, `couple`
    * **`invalid_date_format`** - La date doit suivre le format `YYYY-MM-DD` (par exemple, 2012-05-08)
    * **`invalid_travel_type`** - Le type doit être l'un des suivants : `hotels`, `flights`
    * **`missing_variation_id`** - ID de variation manquant
    * **`missing_flight_travel_context`** - Champs manquants du contexte de voyage en avion
  </Accordion>

  <Accordion title="Erreurs de Serveur">
    * **`internal_server_error`** - Le serveur a rencontré un problème
    * **`request_canceled`** - L'appelant a annulé la requête
  </Accordion>
</AccordionGroup>

## Problèmes d'Intégration Courants

<CardGroup cols={2}>
  <Card title="Événements Non Affichés" icon="eye-slash">
    **Les événements renvoient 200 mais n'apparaissent pas dans le tableau de bord :**

    * Vérifiez que `occurredAt` est dans les 30 derniers jours
    * Vérifiez que le produit existe dans le catalogue
    * Confirmez l'orthographe du type d'événement (`click`, pas `Click`)
  </Card>

  <Card title="Résultats d'Enchères Vides" icon="rectangle-xmark">
    **Les enchères ne renvoient aucun gagnant :**

    * **Vérifiez le budget de la campagne** (problème le plus courant)
    * **Vérifiez que le solde du compte est positif**
    * Confirmez que les produits sont en stock et actifs
    * Vérifiez que des campagnes actives existent
    * Vérifiez que les montants des enchères ne sont pas trop bas
  </Card>

  <Card title="Problèmes d'Attribution" icon="link-slash">
    **L'attribution ne fonctionne pas correctement :**

    * Consultez notre [Guide de Dépannage d'Attribution](/knowledge-base/ad-platform/reporting/attribution-troubleshooting)
    * Vérifiez que les ID d'enchères résolus sont transmis correctement
    * Vérifiez que les événements d'achat incluent les ID de produit appropriés
  </Card>

  <Card title="Problèmes de Connexion" icon="wifi-slash">
    **Connexion refusée ou délai d'attente :**

    * Testez la connectivité : `curl -I https://api.topsort.com`
    * Vérifiez que le pare-feu autorise le HTTPS sortant (port 443)
    * Mettez en liste blanche les domaines `*.topsort.com`
    * Vérifiez la validation du certificat TLS/SSL
  </Card>
</CardGroup>

<Warning>
  **L'épuisement du budget est la cause n°1 d'enchères vides.** Avant de déboguer des problèmes d'enchères complexes, vérifiez d'abord que vos campagnes ont un budget quotidien et un solde de compte suffisants. Les campagnes avec un budget nul ne peuvent pas participer aux enchères.
</Warning>

## Erreurs de Validation Détaillées

Certains points de terminaison renvoient des erreurs de validation détaillées avec des informations au niveau du champ :

```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"
    }
  ]
}
```

Utilisez le tableau `details` pour identifier exactement quels champs ont des problèmes et ce qui doit être corrigé.

## Limitation de Débit

<CardGroup cols={2}>
  <Card title="Backoff Exponentiel" icon="arrows-rotate">
    Réessayez les requêtes échouées avec des délais croissants entre les tentatives :

    ```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="Utiliser les En-têtes de Limite de Débit" icon="gauge">
    Respectez les en-têtes de limite de débit dans les réponses :

    * `X-RateLimit-Limit` - Total des requêtes autorisées
    * `X-RateLimit-Remaining` - Requêtes restantes
    * `X-RateLimit-Reset` - Quand la limite se réinitialise

    Attendez jusqu'à `X-RateLimit-Reset` avant de réessayer.
  </Card>
</CardGroup>

<Note>
  Les points de terminaison Enchères (`/v2/auctions`) et Événements (`/v2/events`) ne sont **pas limités en débit**. Les limites de débit s'appliquent aux autres points de terminaison comme les APIs de gestion de campagne et de reporting.
</Note>

## Problèmes de Connexion et Réseau

### Liste de Vérification de Dépannage

<Steps>
  <Step title="Tester la Connectivité de Base">
    Vérifiez que vous pouvez atteindre l'API de Topsort :

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

  <Step title="Vérifier les Règles de Pare-feu">
    Assurez-vous que le trafic HTTPS sortant (port 443) est autorisé et mettez en liste blanche :

    * `api.topsort.com`
    * `*.topsort.com`
  </Step>

  <Step title="Vérifier le Support TLS">
    Assurez-vous que votre client HTTP prend en charge les versions TLS modernes :

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

  <Step title="Configurer les Délais d'Attente">
    Définissez des valeurs de délai d'attente appropriées et implémentez une logique de nouvelle tentative :

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

  <Step title="Vérifier la Page de Statut">
    Visitez [topsort.statuspage.io](https://topsort.statuspage.io) pour l'état du service
  </Step>
</Steps>

### Problèmes Réseau Courants

<AccordionGroup>
  <Accordion title="Problèmes de Certificat SSL/TLS">
    **Symptômes :** Erreurs de validation de certificat, échecs de handshake SSL

    **Solutions :**

    * Mettez à jour votre client HTTP pour prendre en charge les versions TLS modernes
    * Assurez-vous que votre système fait confiance aux autorités de certification standard
    * Testez avec : `openssl s_client -connect api.topsort.com:443`
  </Accordion>

  <Accordion title="Problèmes de Pare-feu/Proxy">
    **Symptômes :** Connexion refusée, requêtes suspendues

    **Solutions :**

    * Mettez en liste blanche les domaines Topsort (`api.topsort.com`, `*.topsort.com`)
    * Autorisez le trafic HTTPS sortant sur le port 443
    * Configurez les paramètres de proxy si requis par votre réseau
    * Testez sans proxy pour isoler le problème
  </Accordion>

  <Accordion title="Problèmes de Délai d'Attente">
    **Symptômes :** Requêtes expirant, se suspendant indéfiniment

    **Solutions :**

    * Augmentez les valeurs de délai d'attente dans votre client HTTP
    * Implémentez une logique de nouvelle tentative avec backoff exponentiel
    * Vérifiez les grandes charges utiles de requête dépassant les limites
    * Utilisez le pooling de connexions pour de meilleures performances
  </Accordion>

  <Accordion title="Connectivité Régionale">
    **Symptômes :** Problèmes depuis des régions géographiques spécifiques

    **Solutions :**

    * Testez depuis différents emplacements pour isoler les problèmes régionaux
    * Utilisez un service CDN ou proxy si nécessaire
    * Contactez le support avec les détails de votre emplacement
  </Accordion>
</AccordionGroup>

## Outils de Débogage

<CardGroup cols={2}>
  <Card title="Journaux Développeur" icon="list-check">
    Consultez l'onglet **Dev Tools** dans votre Plateforme Publicitaire pour les journaux détaillés de requête/réponse API.

    Consultez notre [guide des Journaux Développeur](/api-reference/logs) pour l'aide à l'interprétation des entrées de journal.
  </Card>

  <Card title="Page de Statut" icon="signal">
    Surveillez la santé du service et la maintenance planifiée sur [topsort.statuspage.io](https://topsort.statuspage.io)

    Abonnez-vous aux mises à jour pour les notifications en temps réel.
  </Card>
</CardGroup>

## Besoin d'Aide ?

Si vous rencontrez toujours des problèmes après avoir consulté ce guide :

* **Consultez la page de statut :** [topsort.statuspage.io](https://topsort.statuspage.io)
* **Contactez le support** avec les détails d'erreur et les exemples de requêtes API
* **Examinez la documentation API** pour les exigences spécifiques au point de terminaison