Codes d'erreur

Quand un appel échoue, l'API renvoie un code HTTP adapté et un corps JSON décrivant le problème.

Le format

Une erreur contient toujours un objet error avec un code lisible par votre programme et un message lisible par un humain :

{
  "error": {
    "code": "insufficient_scope",
    "message": "Scope manquant : write:quotes."
  }
}

Sur une erreur de validation du corps de la requête, un champ details liste les problèmes champ par champ :

{
  "error": {
    "code": "invalid_body",
    "message": "Le corps de la requête est invalide.",
    "details": [
      { "path": "clientEmail", "message": "Adresse email invalide." }
    ]
  }
}

La liste des codes

HTTP	code	Sens
400	invalid_request	Paramètre invalide (par exemple, un statut inconnu)
400	invalid_body	JSON malformé ou validation échouée (voir details)
400	invalid_idempotency_key	En-tête Idempotency-Key mal formé (longueur hors 8–255)
401	missing_authorization	En-tête Authorization absent
401	invalid_key_format	Format de clé invalide
401	invalid_key	Clé inconnue ou invalide
401	revoked_key	Clé révoquée
401	expired_key	Clé expirée
403	insufficient_scope	Scope requis absent
404	not_found	Ressource introuvable (aussi company_not_found, contact_not_found, opportunity_not_found)
409	invoice_not_draft, quote_not_draft, contact_email_duplicate	Action impossible dans l'état actuel (voir ci-dessous)
422	stock_adjust_failed	Règle métier refusée (mouvement ou ajustement de stock)
429	rate_limited	Limite de débit dépassée
500	internal_error	Erreur interne

Le 409 : action impossible dans l'état actuel

Un 409 signale que l'action demandée n'a pas de sens dans l'état où se trouve la ressource, l'appel est bien formé, mais l'état l'interdit. Le code précise le cas :

• invoice_not_draft : modifier ou supprimer une facture qui n'est plus en brouillon.
• quote_not_draft : modifier, supprimer ou « marquer envoyé » un devis qui n'est plus en brouillon (POST /quotes/{id}/send).
• contact_email_duplicate : créer un contact avec un email déjà présent.

Inutile de retenter à l'identique : il faut d'abord changer l'état de la ressource (repasser par un brouillon, utiliser un autre email…).

Le 422 : validation métier échouée

Un 422 signale qu'une règle métier a refusé l'opération. À la différence du 400 invalid_body (le corps est mal formé), ici le corps est valide mais le moteur refuse l'effet. Le code est stock_adjust_failed quand un mouvement ou un ajustement est refusé par la politique de stock négatif.

Le 207 : traitement partiel

Certaines écritures par lot, notamment POST /stock-movements, peuvent réussir partiellement. Le serveur renvoie alors un 207 : une partie des éléments est appliquée (applied), l'autre est en erreur (errors). Un 200 signifie que tout est passé ; un 422 stock_adjust_failed, que rien n'est passé. Dans tous les cas, parcourez errors.

Voir aussi

• Scopes et permissions
• Limites de débit