Passer au contenu principal

​
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 :
ChampTypeDescription
errCodestringChaîne courte identifiant uniquement le problème
docUrlstringLien vers la documentation fournissant plus d’informations
messagestringExplication facultative lisible par l’homme (peut changer avec le temps)

​
Codes de Statut HTTP

400 - Bad Request

Format de requête inacceptable ou syntaxe incorrecte. Vérifiez la structure de la requête par rapport aux spécifications de l’API.

403 - Forbidden

Problème de clé API ou jetons d’autorisation manquants. Vérifiez vos identifiants d’authentification.

404 - Not Found

La ressource n’existe pas ou l’URL est incorrecte. Vérifiez le chemin du point de terminaison et l’ID de la ressource.

422 - Unprocessable Entity

Le corps de la requête ne correspond pas au modèle attendu. Champs requis manquants ou types de données incorrects.

429 - Rate Limit

Trop de requêtes. Vérifiez les en-têtes de limite de taux : X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

5xx - Server Error

Problème de serveur inattendu. Notre équipe résout généralement ces problèmes rapidement. Consultez la page de statut.

​
Codes d’Erreur Spécifiques

  • invalid_api_key - La clé API dans l’en-tête d’autorisation est manquante, invalide ou a expiré. Voir authentification pour plus de détails.
  • 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
  • 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
  • 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
  • invalid_category - Un seul parmi id, ids ou disjunctions doit être défini, où aucun tableau n’est plus long que 5
  • invalid_opaque_user_id - La valeur de l’ID utilisateur opaque ne doit pas dépasser 90 caractères
  • 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
  • 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
  • invalid_device - L’appareil doit être l’un des suivants : desktop ou mobile
  • too_many_search_query_words - Limite de mots de requête de recherche dans la requête dépassée
  • 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
  • no_purchase_items - Au moins un article doit être acheté
  • missing_purchased_at - Champ requis purchasedAt manquant
  • 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
  • experiment_variant_too_long - Les variantes d’expérimentation de marketplace ont une longueur maximale de 10 caractères
  • no_listing_experiment_variant - Les variantes d’expérimentation de marketplace ne sont prises en charge que pour les enchères de listes sponsorisées
  • 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
  • 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
  • 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
  • internal_server_error - Le serveur a rencontré un problème
  • request_canceled - L’appelant a annulé la requête

​
Problèmes d’Intégration Courants

Événements Non Affichés

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)

Résultats d'Enchères Vides

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

Problèmes d'Attribution

L’attribution ne fonctionne pas correctement :
  • Consultez notre Guide de Dépannage d’Attribution
  • 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

Problèmes de Connexion

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

​
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 : 
{
  "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

Backoff Exponentiel

Réessayez les requêtes échouées avec des délais croissants entre les tentatives :
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)

Utiliser les En-têtes de Limite de Débit

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

​
Problèmes de Connexion et Réseau

​
Liste de Vérification de Dépannage

1

Tester la Connectivité de Base

Vérifiez que vous pouvez atteindre l’API de Topsort :
curl -I https://api.topsort.com
2

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
3

Vérifier le Support TLS

Assurez-vous que votre client HTTP prend en charge les versions TLS modernes :
openssl s_client -connect api.topsort.com:443
4

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 :
session = requests.Session()
session.timeout = (10, 30)  # (connect, read)
5

Vérifier la Page de Statut

Visitez topsort.statuspage.io pour l’état du service

​
Problèmes Réseau Courants

Symptômes : Erreurs de validation de certificat, échecs de handshake SSLSolutions :
  • 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
Symptômes : Connexion refusée, requêtes suspenduesSolutions :
  • 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
Symptômes : Requêtes expirant, se suspendant indéfinimentSolutions :
  • 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
Symptômes : Problèmes depuis des régions géographiques spécifiquesSolutions :
  • 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

​
Outils de Débogage

Journaux Développeur

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 pour l’aide à l’interprétation des entrées de journal.

Page de Statut

Surveillez la santé du service et la maintenance planifiée sur topsort.statuspage.ioAbonnez-vous aux mises à jour pour les notifications en temps réel.

​
Besoin d’Aide ?

Si vous rencontrez toujours des problèmes après avoir consulté ce guide :
  • Consultez la page de statut : 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