Enveloppe d'erreur
{
"error": {
"code": "asset_not_found",
"message": "No asset with id 42 for this shop",
"status": 404,
"request_id": "req_..."
}
}Indiquez le request id lorsque vous contactez le support.
Codes d'erreur courants
| HTTP | Code | Signification |
|---|---|---|
| 400 | invalid_request | JSON mal formé ou champ manquant. |
| 400 | idempotency_key_required | Requête d'écriture sans Idempotency-Key. |
| 401 | unauthorized | Jeton manquant, invalide, inconnu ou révoqué. |
| 402 | plan_required | La boutique est sur la formule Free. L'API externe nécessite une formule payante. Pour une notification de mise à jour de produit, ce code signifie aussi que l'abonnement de la boutique n'est pas actif, et une campagne arrêtée pour l'une ou l'autre raison après sa mise en file d'attente signale error: plan_required sur GET /notifications/{id}. |
| 403 | forbidden | L'API externe est désactivée (l'interrupteur d'arrêt global), il manque à la clé d'API une portée dont la requête a besoin, ou, sur les routes des notifications de mise à jour de produit, Alva a désactivé ces notifications comme frein d'urgence. Contactez-nous si une clé disposant des bonnes portées la reçoit. |
| 403 | notifications_suspended | Les notifications de mise à jour de produit sont suspendues pour cette boutique à la suite de plaintes pour spam sur des campagnes précédentes. Aucune nouvelle tentative n'y changera rien — contactez le support. |
| 404 | asset_not_found, mapping_not_found, order_not_found, category_not_found, job_not_found | La ressource est introuvable ou appartient à une autre boutique. |
| 404 | notification_not_found | La notification de mise à jour de produit est introuvable ou appartient à une autre boutique. |
| 409 | idempotency_conflict | La même clé a été réutilisée avec une requête différente. |
| 409 | stamping_in_progress | Le renvoi est bloqué tant que le filigranage du PDF est en attente. |
| 409 | delivery_not_yet_released | Le produit a un délai de livraison de téléchargement configuré et les fichiers de l'acheteur ne sont pas encore débloqués. error.details.release_at est l'instant ISO 8601 du déblocage ; le marchand peut libérer la commande par anticipation avec le point de terminaison grant-downloads. |
| 409 | notification_not_cancellable | Seule une notification de mise à jour de produit en file d'attente peut être annulée. Celle-ci a déjà commencé à être envoyée, est terminée, a échoué ou a été annulée — error.details.status précise lequel. |
| 409 | app_not_installed | Alva n'a aucune session Shopify active pour la boutique, généralement parce que l'application a été désinstallée : une requête qui a besoin de Shopify ne peut donc pas s'exécuter — une écriture de mapping, ou une notification de mise à jour de produit dont la note fait appel à un métachamp ou qui envoie variant_ids. Ouvrez ou réinstallez l'application dans l'admin Shopify, puis réessayez. |
| 409 | multiple_mappings_match | Un id Shopify correspond à plus d'un mapping, Alva ne peut donc pas savoir lequel vous visez. Sur POST /products/{id}/notifications, error.details.ambiguous_variant_ids liste les variantes demandées que plus d'un mapping dessert. |
| 409 | personalized_product | Le produit est personnalisé. La personnalisation est définie pour tout le produit : POST /mappings avec shopify_variant_ids ne peut donc pas lui ajouter de mapping propre à une variante (rien n'est écrit), et POST /products/{id}/notifications ne peut pas notifier ses acheteurs, car chaque commande a son propre fichier. |
| 422 | storage_quota_exceeded | Le téléversement ou l'import dépasserait le quota de stockage. |
| 422 | key_limit_reached | La boutique détient déjà le maximum de 25 clés d'API actives ; révoquez-en une d'abord. |
| 422 | withdrawal_consent_required | La boutique a activé le consentement au droit de rétractation de l'UE et la commande n'a pas encore d'enregistrement de consentement ; les URL de téléchargement sont émises dès que le client consent. |
| 422 | email_disabled | Les e-mails aux clients sont désactivés dans les paramètres e-mail de l'application. Renvoyé par un renvoi d'e-mail de commande, par POST /orders/{id}/assignments avec send_email: true (rien n'est créé), par POST /products/{id}/notifications, et comme résultat de notify_customers lors d'une écriture de mapping (le mapping lui-même est bien enregistré). Activez-les, puis réessayez. |
| 422 | invalid_message | La note de mise à jour de produit a enfreint une règle : vide, trop longue (y compris une fois ses variables remplies), une variable inconnue ou non fermée, plus de cinq métachamps différents, un lien ou une adresse e-mail (y compris dans la valeur d'un métachamp), ou un métachamp manquant, trop long ou d'un type qui ne peut pas être affiché dans un e-mail. error.details.errors[] nomme chaque règle ; error.details.max_length est le plafond (2 000). Rien n'a été envoyé ni écrit. Lors d'une écriture de mapping avec notify_customers, seules les règles portant sur le texte même de la note refusent l'écriture ; un problème de métachamp est signalé dans data.notification une fois le mapping enregistré. |
| 422 | no_downloadable_content | Aucun mapping ciblé ne contient de fichiers, de packs ou de liens à annoncer ; les mappings à clés uniquement et personnalisés ne peuvent pas faire l'objet d'une mise à jour de produit. Avec variant_ids, lorsque le produit a un autre mapping qui pourrait être notifié, error.details.mapping_ids indique les mappings auxquels ces variantes ont été résolues. |
| 422 | no_eligible_recipients | Personne à qui écrire : aucun acheteur des mappings ciblés n'est abonné. error.details.opted_out_count indique combien se sont désabonnés. Un mapping tout neuf n'a pas encore d'acheteurs. |
| 429 | rate_limited | La limite de clés d'API ou de renvois de commande a été atteinte. |
| 429 | notification_cooldown | Une notification de mise à jour de produit par produit tous les 7 jours, toutes variantes et toutes sources confondues — ou une campagne pour ce produit est encore en file d'attente ou en cours d'envoi. Ce n'est pas le seau à jetons : Retry-After peut atteindre sept jours et error.details.next_available_at est l'instant où le produit redevient libre. Ne réessayez pas automatiquement — planifiez le prochain appel à next_available_at. Annuler une campagne ne réinitialise pas la limite ; utilisez dry_run pour vérifier une note avant l'envoi. |
| 429 | too_many_active_notifications | La boutique a déjà 5 notifications de mise à jour de produit en file d'attente ou en cours d'envoi, tous produits et toutes sources confondus. error.details.limit est le plafond et error.details.active_notification_ids liste ces campagnes, de la plus ancienne à la plus récente. Il n'y a pas de Retry-After : interrogez régulièrement GET /notifications/{id} pour l'une d'elles et réessayez une fois qu'elle est terminée. Une simulation est refusée de la même manière ; lors d'une écriture de mapping, le refus est signalé dans data.notification à la place. |
| 500 | internal_error | Erreur serveur inattendue. Sur POST /products/{id}/notifications, chaque 500 libère l'Idempotency-Key : réessayez donc la même requête avec la même clé. Trois cas y sont attendus : Shopify n'a pas pu renvoyer les métachamps du produit pour la note, Shopify n'a pas pu confirmer les variant_ids demandés, ou la création a attendu plus de 8 secondes derrière les autres créations de la boutique. Si la tentative échouée a malgré tout mis la campagne en file d'attente, la nouvelle tentative est refusée avec 429 notification_cooldown au lieu d'en lancer une seconde. |
Documentation de l'API
Cet article vous a-t-il été utile ?
Dernière mise à jour 2026-10-20