Limites de debit & erreurs

Quota par offre

Les quotas mensuels d'extraction sont remis a zero le premier jour de chaque mois UTC. Le quota est compte apres finalisation et enregistrement d'une extraction reussie.

Gerer les 429

L'API peut renvoyer 429 Too Many Requests pour deux raisons:

Utilisez un backoff exponentiel pour rate_limit_exceeded, et arretez le trafic d'extraction ou changez d'offre pour quota_exceeded.

import random
import time

import httpx


def extract_with_retry(text: str, api_key: str, max_retries: int = 5) -> dict:
    delay = 1.0
    for _ in range(max_retries):
        response = httpx.post(
            "https://api.parsurai.com/v1/extract",
            headers={"X-API-Key": api_key},
            json={"text": text, "locale": "auto"},
        )
        if response.status_code != 429:
            response.raise_for_status()
            return response.json()

        body = response.json()
        if body.get("error", {}).get("code") == "quota_exceeded":
            raise RuntimeError(body["error"]["message"])

        retry_after = int(response.headers.get("Retry-After", "60"))
        time.sleep(retry_after + random.uniform(0, delay))
        delay = min(delay * 2, 60)

    raise RuntimeError("Max retries exceeded")

async function extractWithRetry(text, apiKey, maxRetries = 5) {
  let delay = 1000;

  for (let attempt = 0; attempt < maxRetries; attempt += 1) {
    const res = await fetch('https://api.parsurai.com/v1/extract', {
      method: 'POST',
      headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify({ text, locale: 'auto' }),
    });

    if (res.status !== 429) {
      if (!res.ok) throw new Error(`API error: ${res.status}`);
      return res.json();
    }

    const body = await res.json();
    if (body.error?.code === 'quota_exceeded') {
      throw new Error(body.error.message);
    }

    const retryAfter = Number(res.headers.get('Retry-After') ?? '60') * 1000;
    await new Promise((resolve) => setTimeout(resolve, retryAfter + Math.random() * delay));
    delay = Math.min(delay * 2, 60000);
  }

  throw new Error('Max retries exceeded');
}

Gerer les 503 et 504

Deux autres reponses decrivent le service et non votre requete. Les deux peuvent etre reessayees sans risque:

Aucune des deux ne porte d'en-tete Retry-After. Reutilisez le backoff exponentiel ci-dessus en partant d'environ une seconde. Ne reessayez un 504 que quelques fois: un document qui expire de maniere repetee est trop couteux pour cet endpoint, la solution est de le decouper.

Format d'erreur

Toutes les erreurs applicatives utilisent la meme enveloppe JSON:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Quota d'extractions mensuelles depasse. Veuillez mettre a niveau votre plan pour continuer.",
    "upgrade_url": "https://invoice-extractor.com/pricing"
  }
}

upgrade_url existe uniquement pour les erreurs de quota et de restriction d'offre.

Reference complete des codes d'erreur

Recommandations de suivi

• Appelez GET /v1/usage pour lire calls_this_month, quota, plan_name et resets_on.
• Activez les alertes de quota dans Dashboard > Parametres > Notifications.
• Alertez quand calls_this_month / quota depasse votre seuil interne.

Decisions de restriction par offre

Certaines requetes sont syntaxiquement valides mais bloquees par l'offre courante. Elles renvoient 402 avec feature_not_in_plan et ne consomment pas le quota d'extraction.

Exemple de reponse usage

curl https://api.parsurai.com/v1/usage \
  -H "X-API-Key: $PARSURAI_API_KEY"

{
  "calls_this_month": 318,
  "quota": 2000,
  "plan_name": "starter",
  "resets_on": "2026-07-01"
}