Développeurs · Guides

Traitez chaque refus et réessayez sans créer de doublon

Un appel en échec à l’API d’Ultineo E-commerce utilise la même enveloppe qu’un appel réussi : lisez le code de statut HTTP, puis le message dans response. Ce guide classe les statuts selon ce que chacun demande à votre programme.

Ce qu’il faut savoir avant de gérer les erreurs

Une enveloppe, même en échec

Un refus porte les trois clés de toute réponse, code, title et response, et sa clé response est une chaîne qui décrit ce qui n’a pas fonctionné. La page « Conventions de l’API » décrit l’enveloppe.

Le code de statut décide

Les messages sont des phrases en anglais stables, que vous pouvez journaliser et afficher à un opérateur. Basez votre logique sur le code de statut, pas sur le texte d’un message.

Des limites sur chaque requête

Le corps d’une requête ne dépasse pas 200 000 octets, et chaque ressource a sa propre limite de lot, de 25 à 500 éléments. Un corps plus grand reçoit un 413 et un lot d’import qui dépasse la limite un 422 : envoyez des lots plus petits.

Traitez une réponse dans cet ordre

1

Lisez d’abord le statut

Lisez d’abord le code de statut HTTP, puis lisez response : l’élément ou le rapport d’import en cas de succès, un message explicatif en cas d’échec.

2

Corrigez une requête mal formée

Un 400 signifie que le corps n’est pas un JSON valide, ou qu’une lecture n’a fourni ni la clé de l’élément ni son id. Un 422 sur tout l’appel signifie que items est absent, vide ou au-delà de la limite de lot, ou que tous les éléments ont été refusés.

3

Vérifiez la clé et ses droits

Un 401 signifie qu’aucune clé n’a été envoyée, que l’en-tête Authorization ne commence pas par Bearer, ou que la clé a expiré. Un 403 signifie une clé inconnue ou désactivée, un droit manquant, ou une clé utilisée pour une autre boutique.

4

Vérifiez l’élément et le chemin

Un 404 signifie que l’élément n’existe pas dans votre boutique, ou que le chemin n’existe pas. Vérifiez l’orthographe de la référence, puis comparez le chemin aux tableaux de points d’accès.

5

Réessayez ce qui peut l’être

Un 429, un 503, une connexion interrompue ou un élément refusé avec le code 409 ou 500 peuvent tous être réessayés. Attendez quelques secondes entre deux tentatives, et respectez Retry-After lorsqu’il est présent.

6

Parcourez les éléments refusés

Dans un rapport, chaque élément refusé porte son propre code. Un 422 demande de corriger l’élément, un 404 d’importer d’abord l’élément auquel il fait référence, un 409 de réessayer plus tard, un 500 de le renvoyer.

Un appel refusé et un élément refusé

Le premier exemple est un appel refusé pour un droit manquant : l’enveloppe, avec un message dans response. Le second est un élément refusé : une entrée de la liste data du rapport d’import, tandis que les autres éléments du lot poursuivent leur traitement.

Appel refusé

{
  "code": 403,
  "title": "Forbidden",
  "response": "The API key is missing the required scope: order:write"
}

Votre programme agit sur le code de statut, 403, et le message nomme le droit manquant.

Élément refusé

{
  "index": 3,
  "external_id": "SHP-20931",
  "action": "refused",
  "id": null,
  "code": 409,
  "title": "Conflict",
  "reason": "Another import is already writing this shipment.",
  "notice": []
}

L’entrée donne la position de l’élément dans index et le statut de son refus dans code et title ; ici, reason signale un 409, un élément à réessayer plus tard.

Trois réponses à prévoir

Un 301 sur un appel

Un 301 signifie que vous avez appelé http://. Refaites l’appel en https://, puis appelez directement cette adresse : le guide « Faire votre premier appel » indique ce qu’une requête en clair divulgue.

Un 429 ou un 503

Trop de requêtes en peu de temps reçoivent un 429, et un 503 signifie que le service est temporairement incapable de traiter cette ressource pour votre boutique. Sur un 429, attendez le nombre de secondes indiqué dans l’en-tête Retry-After, puis réessayez ; sur un 503, réessayez plus tard.

Un conflit 409

Sur un import, un 409 signifie que le même élément est déjà en cours d’import par une autre requête, ou qu’un code de bon de réduction est déjà pris : réessayez l’élément plus tard, ou choisissez un autre code. Sur les routes de colis et d’adresses, un 409 signifie que le numéro de suivi ou le contact est déjà détenu, et la réponse porte l’id du colis ou de l’entrée qui le détient.

Les articles derrière cette page

Cette page reprend les articles suivants du centre d’aide. Ils détaillent chaque champ, chaque valeur et chaque réponse.

Codes d’erreur

Vue d’ensemble de l’API

Votre premier appel

Import et export

Modifiez le catalogue en masse avec un résultat lisible

Ouvrir la page

Les pages produit à lire ensuite

Accès API

Reliez vos systèmes avec des accès adaptés à la boutique

Import et export

Modifiez le catalogue en masse avec un résultat lisible

Commandes

Articles, paiements et expéditions liés

Codes promo

Codes, validité et limites d’utilisation

Poursuivre dans cette rubrique

Faire votre premier appel

L’adresse, le contrôle de disponibilité, la clé dans l’en-tête et la lecture de la réponse d’un premier appel.

Ouvrir la page

Gérer les clés et les accès

Qui crée une clé, ce qu’elle peut atteindre, quand elle expire et comment la renommer, la désactiver ou la supprimer.

Ouvrir la page

Importer par lots

Le contrat commun à tous les imports : lots, mode essai, renvoi sans doublon et rapport.

Ouvrir la page

Relier un ERP ou un flux fournisseur

Une connexion type depuis un autre système : clés à faire correspondre, premier essai, synchronisation et contrôles.

Ouvrir la page

Migrer une boutique existante

Reprenez le catalogue, l’historique de ventes et le domaine de votre boutique, en vérifiant chaque étape.

Ouvrir la page

L’IA dans vos logiciels

Un raisonnement ajouté à un écran de votre logiciel, lancé par l’API puis relu par votre code.

Ouvrir la page

Vue d’ensemble développeurs

Connectez votre boutique une fois ouverte

Chaque demande d’ouverture de boutique est étudiée par notre équipe, qui vous répond par e-mail.

Questions

Oui. Chaque import est reconnu élément par élément : renvoyer le même lot ne crée donc jamais de doublon. Les éléments déjà enregistrés reviennent en unchanged.

Un import vérifie chaque élément séparément. Le lot répond 200 lorsqu’au moins un élément a été créé, mis à jour ou laissé inchangé, même si d’autres ont été refusés, et 422 lorsque tous ont été refusés, avec le même rapport pour que vous puissiez en voir la raison.

Le message « The API key doesn’t have permissions to perform the request. » couvre trois cas sans les distinguer : une clé inconnue, une clé désactivée et une clé dont la boutique n’est plus active. Une clé expirée répond en revanche 401, avec son propre message. Le guide « Gérer les clés et les accès » explique pourquoi la réponse est la même.

La méthode n’est pas prise en charge sur ce chemin : le message indique « The parameters were valid but the request failed. ». Seuls GET et POST sont servis, ainsi que PATCH et DELETE sur les routes de colis et d’adresses.