Codes d'erreur
Un appel en échec utilise la même enveloppe qu'un appel réussi : lisez le code de statut HTTP, puis lisez response pour obtenir un message décrivant le problème. Les messages sont des phrases en anglais stables, que vous pouvez journaliser et afficher à un opérateur, mais basez votre logique sur le code de statut.
{
"code": 403,
"title": "Forbidden",
"response": "The API key is missing the required scope: order:write"
}| Champ | Type | Description |
|---|---|---|
code | entier | Le code de statut HTTP, répété dans le corps. |
title | chaîne | Le libellé court du statut. |
response | chaîne | Ce qui n'a pas fonctionné. |
Remarque — Le
404pour un chemin inconnu et le429décrit ci-dessous sont renvoyés avant que votre requête n'atteigne un point d'accès ; dans ces deux réponses,codeest une chaîne ("404","429"). Fiez-vous au code de statut HTTP plutôt qu'au type de ce champ.
Codes de statut
| Code | Statut | Description |
|---|---|---|
| 200 | OK | Une lecture a réussi, ou un import a accepté au moins un élément. Lisez le rapport ligne par ligne : certains éléments peuvent tout de même être refusés, et vérifiez le champ dry_run qu'il renvoie. |
| 301 | Moved Permanently | Vous avez appelé http://. Refaites l'appel en https://. |
| 400 | Bad Request | Une lecture ne désignait aucun élément (le paramètre de lecture est absent), ou le corps de la requête n'est pas un JSON valide. |
| 401 | Unauthorized | Aucune clé n'a été envoyée, l'en-tête Authorization ne commence pas par Bearer , ou la clé a expiré. |
| 403 | Forbidden | La clé est inconnue ou désactivée, elle ne détient pas le droit nécessaire à l'appel, ou elle a été utilisée pour une autre boutique. |
| 404 | Not Found | L'élément n'existe pas dans votre boutique — y compris un élément qui appartient à une autre boutique — ou le chemin n'existe pas. |
| 409 | Conflict | Le même élément est déjà en cours d'import par une autre requête, ou un code de bon de réduction est déjà pris. |
| 413 | Payload Too Large | Le corps de la requête dépasse 200 000 octets. Envoyez des lots plus petits. |
| 422 | Unprocessable Entity | Le lot entier a été refusé : tous les éléments ont été refusés, items est absent ou vide, ou le lot dépasse la limite de la ressource. |
| 429 | Too Many Requests | Trop de requêtes en peu de temps. Attendez le nombre de secondes indiqué dans l'en-tête Retry-After, puis réessayez. |
| 503 | Service Unavailable | Le service est temporairement incapable de traiter cette ressource pour votre boutique. Réessayez plus tard. |
Échecs d'authentification
Ces contrôles ont lieu avant tout le reste, sur chaque chemin.
| Code | Message | Cause |
|---|---|---|
| 401 | No valid API key provided. | L'en-tête Authorization est absent, ne commence pas par Bearer , ou ne contient pas une clé de boutique. |
| 401 | The API key has expired. | La clé avait une date d'expiration et celle-ci est dépassée. Une clé sans date d'expiration ne déclenche jamais cette erreur. |
| 403 | The API key doesn't have permissions to perform the request. | La clé est inconnue ou désactivée, ou sa boutique n'est plus active. |
Remarque — Une clé inconnue et une clé désactivée donnent le même
403avec le même message, volontairement : l'API ne confirme jamais l'existence d'une clé.
Échecs liés aux droits et à la boutique
| Code | Message | Cause |
|---|---|---|
| 403 | The API key is missing the required scope: <scope> | La clé ne détient ni *, ni <resource>:*, ni le droit nommé. Ajoutez le droit à la clé, ou cessez d'appeler ce point d'accès. |
| 403 | This API key can only read and write its own project. | La requête désignait un project autre que la boutique de la clé. Retirez le champ project : la clé désigne déjà votre boutique. |
| 403 | This API key is not attached to a project. | La clé n'est liée à aucune boutique. Utilisez une clé créée pour votre boutique. |
Échecs de requête
| Code | Message | Cause |
|---|---|---|
| 400 | Invalid JSON. | Le corps n'est pas un JSON analysable, ou est une valeur JSON qui n'est pas un objet. |
| 400 | Missing required parameter: <name>. | Une lecture n'a fourni ni la clé de l'élément ni son id. La rubrique de chaque ressource liste ses paramètres de lecture. |
| 400 | Name the customer to read: … / Name the payment to read: … | Le même cas sur les lectures de clients et de paiements. |
| 413 | Request body too large. | Le corps a dépassé 200 000 octets. |
| 422 | Missing required field: items (…). | Le corps ne contient pas de liste items, ou items n'est pas une liste. La formulation varie légèrement d'une ressource à l'autre. |
| 422 | items is empty. | La liste items ne contient aucun élément. |
| 422 | A batch carries at most <limit> <records>. | Le lot dépasse la limite de la ressource, indiquée dans chaque tableau de points d'accès. Divisez-le. |
| 422 | The parameters were valid but the request failed. | La méthode n'est pas prise en charge sur ce chemin. Seuls GET et POST sont servis. |
Introuvable
| Code | Message | Cause |
|---|---|---|
| 404 | <Record> not found. | Aucun élément de votre boutique ne correspond à la clé ou à l'id lu, par exemple Order not found. Un élément d'une autre boutique répond de la même façon. Vérifiez l'orthographe de la référence. |
| 404 | The requested resource was not found. | Le chemin lui-même n'existe pas. Comparez-le aux tableaux de points d'accès. |
Refus au sein d'un lot
Un import vérifie chaque élément séparément. Un élément qui échoue à un contrôle est signalé dans la liste data de la réponse avec "action": "refused", le code et le libellé de statut du refus dans code et title, et ce qu'il faut corriger dans reason. Les autres éléments du lot poursuivent leur traitement.
{
"index": 3,
"external_id": "SHP-20931",
"action": "refused",
"id": null,
"code": 409,
"title": "Conflict",
"reason": "Another import is already writing this shipment.",
"notice": []
}code d'un élément refusé | Signification | Que faire |
|---|---|---|
| 422 | Une valeur est invalide ou un champ obligatoire est absent ; reason nomme le champ. | Corrigez l'élément et renvoyez-le. |
| 404 | L'élément fait référence à un élément absent de votre boutique, par exemple une commande dont le client n'a pas été importé. | Importez d'abord l'élément auquel il fait référence. |
| 409 | Une autre requête importe le même élément en ce moment, ou un code de bon de réduction est déjà détenu par un autre code. | Réessayez l'élément plus tard, ou choisissez un autre code. |
| 500 | L'élément n'a pas pu être enregistré. | Renvoyez l'élément ; l'import peut être rejoué sans risque. |
Un lot répond donc :
200lorsqu'au moins un élément a été créé, mis à jour ou laissé inchangé — même si d'autres ont été refusés ;422lorsque tous les éléments ont été refusés, avec le même rapport pour que vous puissiez en voir la raison.
Réessayer sans risque
Un 429, un 503, une connexion interrompue ou un élément refusé avec le code 409 ou 500 peuvent tous être réessayés. Chaque import est reconnu élément par élément : renvoyer le même lot ne crée donc jamais de doublon, et les éléments déjà enregistrés reviennent en unchanged. Attendez quelques secondes entre deux tentatives, et respectez Retry-After lorsqu'il est présent.