Ratenbegrenzungen & Fehler

Kontingent nach Tarif

Monatliche Extraktionskontingente werden am ersten Tag jedes UTC-Monats zurueckgesetzt. Das Kontingent wird gezaehlt, nachdem eine erfolgreiche Extraktion finalisiert und gespeichert wurde.

Umgang mit 429

Die API kann aus zwei Gruenden 429 Too Many Requests zurueckgeben:

Nutzen Sie exponentielles Backoff fuer rate_limit_exceeded. Stoppen Sie Extraktionstraffic oder wechseln Sie den Tarif bei 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');
}

Umgang mit 503 und 504

Zwei weitere Antworten beschreiben den Dienst statt Ihrer Anfrage. Beide koennen gefahrlos wiederholt werden:

Keine der beiden enthaelt einen Retry-After-Header. Nutzen Sie dasselbe exponentielle Backoff wie oben, beginnend bei etwa einer Sekunde. Wiederholen Sie ein 504 nur wenige Male: Ein Dokument, das wiederholt in den Timeout laeuft, ist fuer diesen Endpunkt zu teuer -- teilen Sie es auf.

Fehlerformat

Alle Anwendungsfehler verwenden dieselbe JSON-Huelle:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monatliches Extraktionskontingent ueberschritten. Bitte upgraden Sie Ihren Plan, um fortzufahren.",
    "upgrade_url": "https://invoice-extractor.com/pricing"
  }
}

upgrade_url ist nur bei Kontingent- und Tarifgating-Fehlern vorhanden.

Vollstaendige Fehlercode-Referenz

Monitoring-Empfehlungen

• Fragen Sie GET /v1/usage ab, um calls_this_month, quota, plan_name und resets_on zu lesen.
• Aktivieren Sie Kontingentwarnungen unter Dashboard > Einstellungen > Benachrichtigungen.
• Alarmieren Sie, wenn calls_this_month / quota Ihren internen Grenzwert ueberschreitet.

Entscheidungen bei Tarif-Gating

Einige Anfragen sind syntaktisch gueltig, werden aber vom aktuellen Tarif blockiert. Diese Antworten verwenden 402 mit feature_not_in_plan und verbrauchen kein Extraktionskontingent.

Usage-Antwortbeispiel

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"
}