Codes d'erreur

Codes de statut HTTP de Listings API, codes d’erreur SYxxxxx pour Listings et Social, et trois formats de réponse d’erreur de l’API v4.

Listings API utilise les codes de statut HTTP conventionnels pour indiquer le résultat d'une requête. Les codes d'erreur portent le préfixe SY et sont inclus dans la chaîne message de l'erreur, au format SYxxxxx: <human-readable reason>.

Codes de statut HTTP

Trois structures de réponse

La plupart des échecs contiennent un tableau errors, soit au premier niveau, soit imbriqué dans le résultat de l'opération, comme le montrent les sections ci-dessous. Quelques échecs renvoient à la place un seul objet error : la limitation de débit (429) et certains échecs au niveau de la requête (400/500 avec un code tel que INTERNAL_SERVER_ERROR). Vérifiez les deux cas : errors est un tableau, error est un objet.

1. Au niveau de la requête : errors[] au premier niveau

Les échecs d'authentification, d'autorisation et ceux dus à une requête mal formée interrompent le traitement avant l'exécution de l'opération. Ils renvoient le statut 4xx correspondant (ci-dessus), avec l'erreur au premier niveau de la réponse.

{  "data": { "createLocation": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

2. Validation des écritures : data.<operation>.errors[] imbriqué

Une requête de création, de mise à jour ou de publication par ailleurs bien formée renvoie HTTP 200. Si les données d'entrée enfreignent une règle métier, l'échec est signalé dans data.<operation>.errors, imbriqué dans la charge utile propre à l'opération. En cas de succès, ce tableau est présent et vide ("errors": []).

{  "data": {    "createLocation": {      "errors": [        { "message": "SY10126: City is Mandatory" },        { "message": "SY10010: state_iso" }      ],      "location": null    }  }}

3. Au niveau de la passerelle : un seul objet error au premier niveau

La limitation de débit et les défaillances inattendues de la passerelle interrompent le traitement avant la traduction et renvoient un objet error contenant un code, un message et un correlation_id. Consultez rate_limited ci-dessous pour le corps de la réponse 429.

Lisez toujours data.<operation>.errors lors d'une écriture, même en cas de statut 200 avec un objet data.<operation> renseigné : une écriture peut échouer partiellement et le signaler ici.

Une réponse 402 Payment Required ne comporte pas d'enveloppe error : code, message, doc_url et, lorsqu'une facture est à payer, pay_url se trouvent au premier niveau. Consultez payment_required ci-dessous.

Réessayer une écriture n'est pas sans conséquences

L'API v4 ne prend pas en charge Idempotency-Key : l'en-tête est ignoré et aucun point de terminaison ne détecte les écritures répétées. Un appel de création, de mise à jour ou de publication qui dépasse le délai d'attente ou renvoie un statut 5xx peut tout de même avoir été enregistré sur le serveur ; réessayer sans vérification peut donc créer un doublon d'établissement, de publication ou de réponse à un avis.

Vous pouvez réessayer librement les lectures avec un délai d'attente croissant. Pour une écriture, effectuez d'abord une lecture de vérification : recherchez l'enregistrement à l'aide d'une clé que vous maîtrisez (storeId, un code de magasin, la liste des réponses de l'interaction) et ne répétez l'appel que si l'enregistrement est réellement absent.

Codes courants

Les codes de validation de la plage SY10xxx correspondent à un champ d’entrée précis ; message indique le champ ou la règle dont la validation a échoué. Les codes d’authentification et d’autorisation de la plage SY90xxx concernent la requête et sont renvoyés au niveau supérieur avec le statut correspondant.

Codes des comptes connectés

Les codes de la plage SY810xx proviennent des points de terminaison Connected Accounts qui importent ou associent une fiche d’une plateforme de publication. Ils sont imbriqués dans le corps de la réponse lors d’un HTTP 200 (structure de réponse 2 ci-dessus), donc lisez data.<operation>.errors même lorsque le statut indique un succès.

Codes Social

Les codes de la plage SY950xx proviennent des endpoints Social : marques, connexions et publications sur les réseaux sociaux. Comme les codes des comptes connectés, ils sont imbriqués dans le corps de la réponse lors d’un HTTP 200 ; lisez donc data.<operation>.error (et data.<operation>.errors sur les routes de traitement en masse), même lorsque le statut indique un succès.

SY95042 et SY95044 sont des erreurs liées aux droits du forfait, et non des erreurs de saisie : réessayer sans changer de forfait produira le même échec. SY95045, SY95046, SY95049 et SY95052 sont des erreurs de saisie qui peuvent être corrigées dans la requête suivante.

Codes de droits d'accès à Listings

rate_limited

429 Too Many Requests : le compte a dépassé la limite de débit de son offre. Le corps est la réponse d'erreur standard contenant une indication retry_after_seconds, un correlation_id à citer dans les demandes d'assistance et un doc_url qui renvoie à cette section :

{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Slow down.",    "retry_after_seconds": 30,    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited"  }}

Attendez le délai indiqué par retry_after_seconds (ou par l'en-tête Retry-After lorsqu'il est présent), puis réessayez en augmentant le délai de façon exponentielle entre les tentatives. Consultez Limites de débit pour connaître les limites par offre et obtenir une implémentation de référence de cette temporisation.

payment_required

402 : Le dernier paiement de ce compte a échoué, ce qui suspend tous les points de terminaison /api/v4. Le corps inclut pay_url, la page Stripe de la facture impayée, lorsqu'une telle page est disponible, et l'en-tête de réponse X-Error-Code contient le même code. Vous pouvez toujours ouvrir la page Facturation du tableau de bord pour payer.

{  "code": "payment_required",  "message": "This account has an unpaid invoice, so API access is paused. Pay the invoice to restore access.",  "pay_url": "https://invoice.stripe.com/i/acct_123/test_abc",  "doc_url": "https://listingsapi.com/docs/error-codes#payment_required"}

L'accès est rétabli dans la minute qui suit le règlement de la dernière facture en attente. Si la facture est toujours impayée 3 jours après le premier échec de paiement, l'abonnement Listings est résilié et les établissements du compte sont archivés. Si le compte dispose également d'un abonnement Social actif, il conserve son accès à Social ; sinon, le compte est fermé et ses clés API cessent de fonctionner.

social_payment_required

402 : Le dernier paiement de l'abonnement Social a échoué, ce qui suspend les points de terminaison Social (/api/v4/social/*). Les points de terminaison Listings continuent de fonctionner. Le corps contient les mêmes champs que payment_required, avec "code": "social_payment_required". Si la facture est toujours impayée 3 jours après le premier échec de paiement, l'abonnement Social est résilié et les marques du compte sont archivées. Un compte sans abonnement Listings est fermé et ses clés API cessent de fonctionner.

Erreurs du plan de contrôle du portail développeur

Les points de terminaison de gestion des comptes et des clés du portail développeur (les routes API propres au tableau de bord) renvoient une réponse d'erreur structurée de format unique, distincte des formats REST errors[] ci-dessus. Chaque code contient un correlation_id et un doc_url qui renvoie à la section correspondante de cette page.

{  "error": {    "code": "AUTH_INVALID_KEY",    "message": "Session is invalid or expired.",    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#auth_invalid_key"  }}

auth_missing_key

401 : Aucun identifiant n'a été fourni. Reconnectez-vous ou envoyez votre clé sous la forme Authorization: API <your-key>.

auth_invalid_key

401 : La session ou la clé est invalide ou a expiré. Authentifiez-vous à nouveau ou générez une nouvelle clé depuis le tableau de bord.

auth_insufficient_scope

403 : L'identifiant est valide, mais n'autorise pas cette action. Une clé limitée à la lecture ne peut pas appeler les points de terminaison d'écriture ; générez une clé d'écriture si vous en avez besoin.

not_found

404 : La ressource demandée, ou une ressource désignée par son ID, n'existe pas.

conflict

409 : La requête entre en conflit avec l'état actuel de la ressource (par exemple, la révocation d'une clé déjà révoquée).

validation_failed

422 : La validation du corps de la requête a échoué. Les champs field et details de la réponse indiquent la donnée d'entrée en cause.

internal_error

500 : Une erreur inattendue côté serveur. Réessayez une lecture en augmentant le délai de façon exponentielle entre les tentatives ; pour une écriture, relisez d'abord l'enregistrement (consultez Réessayer une écriture n'est pas sans coût). Citez le correlation_id si vous contactez l'assistance.

dependency_unavailable

503 : Un service dont dépend l'API est temporairement indisponible. Réessayez en augmentant le délai entre les tentatives.

Pour 429, consultez rate_limited ci-dessus.

Gestion des erreurs dans le code

Vérifiez d’abord le statut HTTP ; puis, pour les opérations d’écriture, recherchez un tableau errors imbriqué dans le corps de la réponse :

from listingsapi import APIError, ListingsAPI client = ListingsAPI(api_key=os.environ["LISTINGSAPI_KEY"]) try:    location = client.locations.create(input=payload)except APIError as e:    # Raised for a non-2xx status (AuthenticationError, ValidationError, and    # so on) and for an error payload returned inside a 200 body.    raise RuntimeError(f"Listings API error: {e}") from e

Avec l’API HTTP brute, les deux mêmes vérifications sont explicites : d’abord le code de statut, puis le contenu de la réponse :

resp = requests.post(    "https://listingsapi.com/api/v4/locations",    headers={"Authorization": f"API {os.environ['LISTINGSAPI_KEY']}"},    json=payload,    timeout=30,)resp.raise_for_status()body = resp.json() op = (body.get("data") or {}).get("createLocation") or {}if op.get("errors"):    messages = [e["message"] for e in op["errors"]]    raise RuntimeError(f"Listings API error: {messages}")

Le Python SDK effectue ces deux vérifications pour vous : il associe chaque statut HTTP à une exception typée et lève également une exception lorsque des données d’erreur sont renvoyées dans le corps d’une réponse 200.