Erreurs

Quand quelque chose ne va pas, l'API répond avec un code HTTP et un corps JSON qui dit pourquoi. Le message est écrit pour qu'un développeur sache quoi corriger.

La forme d'une erreur#

{
  "error": {
    "code": "insufficient_scope",
    "message": "This token does not carry the required permission: invoices:read",
    "request_id": "81c82f5c6e2eb5aa"
  }
}

Les codes#

Les limites#

Quand on dépasse la limite#

Vous recevez 429 rate_limited et l'en-tête Retry-After : le nombre de secondes à attendre. Une bonne conduite : lire X-RateLimit-Remaining et ralentir avant d'arriver à zéro ; sur un 429, attendre Retry-After, puis reprendre.

// Réessaie après un 429, en respectant Retry-After (trois tentatives au plus).
async function lireAvecPatience(url, options, tentatives = 3) {
  for (let essai = 1; essai <= tentatives; essai++) {
    const reponse = await fetch(url, options);
    if (reponse.status !== 429 || essai === tentatives) return reponse;

    const attente = Number(reponse.headers.get("Retry-After") || 5);
    await new Promise((fini) => setTimeout(fini, attente * 1000));
  }
}

# Réessaie après un 429, en respectant Retry-After (trois tentatives au plus).
import time
import requests

def lire_avec_patience(url, tentatives=3, **options):
    for essai in range(1, tentatives + 1):
        reponse = requests.get(url, **options)
        if reponse.status_code != 429 or essai == tentatives:
            return reponse
        time.sleep(int(reponse.headers.get("Retry-After", 5)))