Erreurs & limites

Chaque erreur dit quoi faire. Une intégration qui traite correctement ces six cas ne demande plus de support.

Codes renvoyés

Code	Signification	Conduite à tenir
`400 invalid_json`	Le corps n'est pas du JSON valide.	Vérifiez l'en-tête Content-Type: application/json et la virgule de trop.
`401 unauthorized`	Clé absente, invalide ou révoquée.	Envoyez « Authorization: Bearer cfk_… ». Une clé révoquée ne redevient jamais valide : créez-en une autre.
`404 not_found`	Ressource inexistante — ou appartenant à un autre vendeur.	Les deux cas donnent la même réponse, volontairement.
`422 validation`	Champ obligatoire manquant ou invalide.	La réponse nomme le champ fautif.
`429 rate_limited`	Trop d'appels sur la dernière minute.	Attendez le délai indiqué par l'en-tête Retry-After, puis reprenez.
`500 server_error`	Incident de notre côté.	Réessayez ; si cela persiste, écrivez au support avec l'heure exacte de l'appel.

Le corps d'une erreur a toujours la même forme :

{"error":"unauthorized","message":"Clé API absente, invalide ou révoquée."}

Le cas particulier du 202

202 n'est pas une erreur : la commande est enregistrée, mais comme « lead endommagé », en attente d'une correction dans l'espace du vendeur. Vous recevez la liste des anomalies, champ par champ.

{"data":{"damaged_id":87,"status":"damaged","issues":[
  {"field":"city","level":"warning","message":"Ville non reconnue : « Casa Blanca »."}
]}}

Traitez-le comme un succès partiel : ne rejouez pas l'appel (vous créeriez un second lead), corrigez plutôt la donnée à la source. Le plus souvent, c'est un nom de ville ou un SKU qui a changé chez vous.

Limite de débit

120 appels par minute et par clé. Au-delà, la réponse est 429 avec un en-tête Retry-After en secondes.

Ne lisez pas /v1/products et /v1/cities à chaque commande : ils changent rarement, une lecture par jour suffit, mise en cache chez vous.
Pour suivre l'état des commandes, préférez les webhooks à une interrogation répétée : c'est plus rapide pour vous, et cela ne consomme aucun appel.
Si vous devez rattraper un retard, parcourez /v1/leads avec since et le curseur before plutôt que de demander chaque référence une par une.

Voir vos propres appels

Dans Applications → API, le vendeur retrouve ses derniers appels avec le code renvoyé et la durée. C'est le moyen le plus court de répondre à « pourquoi mon intégration ne marche pas » : l'appel y figure, ou il n'est jamais arrivé.

Compatibilité

Nous ajoutons des champs, nous n'en retirons pas sans changer de version. Écrivez donc votre code pour ignorer les champs inconnus plutôt que pour refuser une réponse enrichie. Les valeurs de statut, en revanche, peuvent s'allonger : prévoyez un cas « autre » dans vos correspondances.