Erreurs et reprise

Utilisez les codes d'erreur stables pour décider de corriger, d'attendre ou de réessayer.

Action à effectuer

Basez la logique sur le statut HTTP et error.code, et non sur le texte error.message.
Un statut 401 nécessite une authentification valide, 403 des droits ou un forfait appropriés, et 409 une vérification de l'opération ou de la version en conflit.

Accès refusé et nouvelles tentatives

401: 401 ne signifie pas toujours que le jeton a expiré. S’il a expiré, obtenez-en un nouveau et réessayez la lecture une seule fois. Si l’obtention du jeton renvoie 401, vérifiez la clé et arrêtez les tentatives automatiques.
403: En cas de 403, vérifiez les permissions, les restrictions IP et l’offre. Un nouveau jeton ne rétablit pas un accès révoqué.

Authentification

Règles de nouvelle tentative

Limitez les tentatives en cas d'erreur transitoire, avec un délai croissant et aléatoire.
Respectez Retry-After lorsqu'il est présent.
Après l'expiration d'une écriture, son résultat peut être inconnu : conservez le même Idempotency-Key et la requête inchangée pour réessayer cette opération logique.
Le catalogue ci-dessous décrit tous les codes publiés.

Écritures sûres

Limites de requêtes

422 / 409

Pour les prix, un format de devise ou une précision du montant incorrects renvoient 422 request.validation_failed.
Un code de devise valide mais différent de celui de la liste de prix sélectionnée renvoie 409 resource.version_conflict.
Vérifiez le contexte et les versions avant de réessayer.

Catalogue des erreurs

400request.malformedLa requête ne peut pas être analysée.

Action à effectuer: Vérifiez la syntaxe JSON, l'encodage URL et la structure de la requête.
Règles de nouvelle tentative: Réessayez après avoir corrigé la requête.

JSON

{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsLa clé API ou le jeton d'accès est invalide, expiré ou révoqué.

Action à effectuer: Vérifiez l'URL de la boutique et les identifiants. Demandez un nouveau jeton avec une clé API active.
Règles de nouvelle tentative: Réessayez après avoir corrigé l'authentification ; évitez les demandes de jeton répétées avec des identifiants invalides.

JSON

{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.requiredL'en-tête Authorization requis est absent ou son schéma est incorrect.

Action à effectuer: Utilisez ApiKey pour obtenir un jeton et Bearer pour les opérations sur les ressources.
Règles de nouvelle tentative: Réessayez après avoir corrigé l'authentification ; évitez les demandes de jeton répétées avec des identifiants invalides.

JSON

{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverifiedLe service n'a pas pu établir une adresse IP client de confiance.

Action à effectuer: Demandez à l'opérateur de vérifier le chemin d'entrée. N'ajoutez pas vous-même d'en-têtes de transfert d'adresse.
Règles de nouvelle tentative: Réessayez uniquement lorsque les droits d'accès requis sont effectifs.

JSON

{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowedL'adresse IP source ne figure pas dans la liste autorisée de la clé.

Action à effectuer: Utilisez une adresse source approuvée ou demandez à un administrateur habilité de modifier la liste IP de la clé.
Règles de nouvelle tentative: Réessayez uniquement lorsque les droits d'accès requis sont effectifs.

JSON

{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_deniedLa clé ne dispose pas d'une autorisation effective requise pour cette opération.

Action à effectuer: Vérifiez les autorisations requises et conditionnelles, les droits de la clé et l'accès de son émetteur.
Règles de nouvelle tentative: Réessayez uniquement lorsque les droits d'accès requis sont effectifs.

JSON

{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabledL'accès API est désactivé pour cette boutique.

Action à effectuer: Demandez au propriétaire de vérifier le forfait actif et la disponibilité de l'API.
Règles de nouvelle tentative: Réessayez uniquement lorsque les droits d'accès requis sont effectifs.

JSON

{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceededLa modification dépasserait une limite du forfait actuel.

Action à effectuer: Vérifiez la limite de la ressource et adaptez la modification prévue ou le forfait. Une écriture modifiée nécessite une nouvelle clé d'idempotence.
Règles de nouvelle tentative: Réessayez après avoir corrigé la requête.

JSON

{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabledLe forfait actuel ne comprend pas cette opération.

Action à effectuer: Vérifiez le forfait minimal indiqué pour l'opération et les autorisations de la clé.
Règles de nouvelle tentative: Réessayez uniquement lorsque les droits d'accès requis sont effectifs.

JSON

{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blockedUne limite du forfait bloque cette ressource.

Action à effectuer: Demandez au propriétaire de résoudre la restriction liée au forfait.
Règles de nouvelle tentative: Réessayez uniquement lorsque les droits d'accès requis sont effectifs.

JSON

{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_foundLa ressource est absente, supprimée ou indisponible sous cet identifiant.

Action à effectuer: Vérifiez la boutique, le chemin et l'identifiant. Utilisez les identifiants renvoyés par cette boutique.
Règles de nouvelle tentative: Réessayez après avoir corrigé la requête.

JSON

{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowedCe point d'accès ne prend pas en charge cette méthode HTTP.

Action à effectuer: Utilisez la méthode documentée. L'en-tête Allow indique les méthodes prises en charge.
Règles de nouvelle tentative: Réessayez après avoir corrigé la requête.

JSON

{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reusedCette clé d'idempotence appartient à une autre requête.

Action à effectuer: Retrouvez l'opération d'origine. Utilisez une nouvelle clé uniquement pour une nouvelle opération logique intentionnelle.
Règles de nouvelle tentative: Ne forcez pas automatiquement la modification en conflit et ne la renvoyez pas à répétition.

JSON

{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_existsUne valeur unique est en conflit avec une ressource existante.

Action à effectuer: Lisez la ressource existante et décidez de l'utiliser ou de choisir une autre valeur unique.
Règles de nouvelle tentative: Ne forcez pas automatiquement la modification en conflit et ne la renvoyez pas à répétition.

JSON

{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_useD'autres ressources dépendent encore de cette ressource.

Action à effectuer: Examinez les dépendances et modifiez-les ou supprimez-les avec les opérations prises en charge avant de supprimer la ressource.
Règles de nouvelle tentative: Réessayez après avoir résolu les dépendances.

JSON

{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflictL'état métier actuel empêche cette modification.

Action à effectuer: Lisez l'état actuel et choisissez une transition métier valide.
Règles de nouvelle tentative: Ne forcez pas automatiquement la modification en conflit et ne la renvoyez pas à répétition.

JSON

{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflictUne autre écriture a modifié la ressource depuis la version que vous avez lue.

Action à effectuer: Lisez le dernier état, réconciliez votre modification et envoyez la nouvelle expected_version.
Règles de nouvelle tentative: Utilisez une nouvelle clé d'idempotence pour l'opération révisée ; n'écrasez pas les données sans les vérifier.

JSON

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_largeLa requête dépasse la taille maximale autorisée.

Action à effectuer: Réduisez le contenu ou répartissez le travail en opérations individuelles prises en charge.
Règles de nouvelle tentative: Envoyez des opérations plus petites et valides, chacune avec sa propre clé d'idempotence.

JSON

{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_typeLe type de média ou l'encodage du contenu n'est pas pris en charge.

Action à effectuer: Pour les écritures JSON, utilisez Content-Type: application/json et un corps non compressé pris en charge.
Règles de nouvelle tentative: Réessayez après avoir corrigé la requête.

JSON

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failedUn ou plusieurs champs ou paramètres ne passent pas la validation.

Action à effectuer: Examinez error.fields, les champs obligatoires, l'autorisation de null, les identifiants et les valeurs admises. Une écriture modifiée constitue une nouvelle opération logique.
Règles de nouvelle tentative: Réessayez après avoir corrigé la requête.

JSON

{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullLa courte file d’attente de l’API est pleine ; la requête n’a pas commencé à s’exécuter.

Action à effectuer: Mettez les requêtes en file d'attente et respectez l'en-tête Retry-After de la réponse.
Règles de nouvelle tentative: Attendez au moins le nombre de secondes indiqué par Retry-After et ajoutez un délai aléatoire. Pour la même écriture, conservez la clé et le contenu.

JSON

{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutLe délai d’attente dans la file de l’API a expiré ; la requête n’a pas commencé à s’exécuter.

Action à effectuer: Mettez les requêtes en file d'attente et respectez l'en-tête Retry-After de la réponse.
Règles de nouvelle tentative: Attendez au moins le nombre de secondes indiqué par Retry-After et ajoutez un délai aléatoire. Pour la même écriture, conservez la clé et le contenu.

JSON

{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceededLa fréquence des requêtes dépasse la limite applicable.

Action à effectuer: Mettez les requêtes en file d'attente et respectez l'en-tête Retry-After de la réponse.
Règles de nouvelle tentative: Attendez au moins le nombre de secondes indiqué par Retry-After et ajoutez un délai aléatoire. Pour la même écriture, conservez la clé et le contenu.

JSON

{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.errorUne erreur inattendue du service s'est produite.

Action à effectuer: Notez l'identifiant de requête et contactez l'opérateur si le problème persiste. N'inscrivez pas d'identifiants d'accès dans les journaux.
Règles de nouvelle tentative: Limitez les tentatives, avec un délai croissant et aléatoire. Pour la même écriture, conservez l'Idempotency-Key d'origine et le contenu inchangé.

JSON

{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_responseLa passerelle n'a pas reçu de réponse API valide.

Action à effectuer: Conservez l'identifiant de requête. Une réponse en échec ne prouve pas que l'écriture n'a pas été appliquée.
Règles de nouvelle tentative: Limitez les tentatives, avec un délai croissant et aléatoire. Pour la même écriture, conservez l'Idempotency-Key d'origine et le contenu inchangé.

JSON

{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableL'API ne peut temporairement pas traiter la requête.

Action à effectuer: Respectez Retry-After lorsqu'il est présent et conservez l'identifiant de requête si l'indisponibilité persiste.
Règles de nouvelle tentative: Limitez les tentatives, avec un délai croissant et aléatoire. Pour la même écriture, conservez l'Idempotency-Key d'origine et le contenu inchangé.

JSON

{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeoutLa passerelle a dépassé le délai d'attente de l'API.

Action à effectuer: Conservez l'identifiant de requête et considérez le résultat de l'écriture comme inconnu.
Règles de nouvelle tentative: Limitez les tentatives, avec un délai croissant et aléatoire. Pour la même écriture, conservez l'Idempotency-Key d'origine et le contenu inchangé.

JSON

{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}