Erreurs

Toute erreur répond avec la même forme JSON, et un statut HTTP qui indique quoi faire ensuite.

Le format

{
  "code": "customer_not_found",
  "message": "No customer with id cus_123",
  "hint": "Check the customer id",
  "statusCode": 404,
  "requestId": "req_0123456789abcdef"
}
  • code : stable et lisible par une machine ; branchez-vous dessus, pas sur message.
  • message : une phrase pour un humain.
  • hint : ce qu’il faut essayer, quand il y a quelque chose à suggérer.
  • statusCode : le statut HTTP, répété.
  • requestId : req_ suivi de 16 caractères hexadécimaux. Citez-le au support QBill pour qu’il retrouve votre requête.

Codes HTTP

Statut code Quand
400 bad_request Le corps ne passe pas la validation. Quand plusieurs champs sont faux, les messages sont joints par ; . Les champs inconnus du corps sont ignorés.
401 unauthorized Pas de clé, ou clé invalide (voir Authentification et clés).
403 publishable_key_forbidden Une clé publishable utilisée hors des quelques lectures de plans qui lui sont permises.
403 api_key_read_only Une clé read_only a tenté d’écrire.
403 merchant_suspended Le compte est suspendu.
404 par exemple customer_not_found L’objet n’existe pas.
409 par exemple sales_link_busy La requête entre en conflit avec l’état actuel ou avec une autre requête. Lisez code : sales_link_busy peut réussir à la relance, coupon_code_taken non.
429 too_many_requests, rate_limited Limite de débit atteinte, voir ci-dessous.

D’autres erreurs portent leur propre code, comme invoice_not_refundable ou key_mode_mismatch.

Limites de débit

  • 600 requêtes par minute par adresse IP : au-delà, la réponse est 429 too_many_requests.
  • 300 requêtes par minute par clé d’API : au-delà, la réponse est 429 rate_limited. Les réponses portent X-RateLimit-Limit et X-RateLimit-Remaining ; un 429 porte aussi Retry-After, le temps à attendre.

Attendez Retry-After avant de réessayer.

Dans le SDK

Le SDK Node (bientôt sur npm) lève une QBillError pour toute réponse non 2xx, avec status, code, hint et requestId :

try {
  await qbill.subscriptions.create({ customer, plan });
} catch (e) {
  if (e instanceof QBillError) {
    console.error(e.status, e.code, e.hint, e.requestId);
  }
  throw e;
}

Le SDK réessaie aussi pour vous, maxRetries fois (2 par défaut, réglable dans les options du constructeur). Il respecte Retry-After sur un 429. Les appels qu’on peut répéter sans risque sont aussi réessayés après un délai dépassé ou une erreur serveur. Voir Webhooks pour les événements reçus par vos endpoints.

← WebhooksRéférence API →