Fehler & Rate-Limits

Fehlerformat

Alle Fehlerantworten folgen einem einheitlichen Format:

{
  "success": false,
  "error": "Beschreibung des Fehlers"
}

HTTP-Statuscodes

Code	Bedeutung
`200`	Erfolg - Anfrage abgeschlossen.
`201`	Erstellt - Ressource wurde erfolgreich erstellt.
`202`	Akzeptiert - Datei hochgeladen, Dokumentdatensatz wird in Kürze erstellt.
`400`	Fehlerhafte Anfrage - fehlende oder ungültige Parameter, nicht unterstützter Dateityp oder Content-Type-Abweichung.
`401`	Nicht autorisiert - fehlender oder ungültiger API-Schlüssel.
`403`	Verboten - API-Schlüssel hat nicht die erforderliche Berechtigung oder den Space-Zugriff.
`404`	Nicht gefunden - Ressource existiert nicht oder ist nicht zugänglich.
`413`	Nutzlast zu groß - hochgeladene Datei überschreitet das 50-MB-Limit.
`429`	Zu viele Anfragen - Rate-Limit überschritten (60 Anfragen pro Minute pro API-Schlüssel; Dokument-Uploads sind auf 10 pro Minute begrenzt).
`500`	Interner Serverfehler - auf unserer Seite ist etwas schiefgelaufen.

Hinweis zu Duplikaten: Der Upload einer Datei, die bereits in deinem Archiv existiert, wird nicht mit einem Fehler abgelehnt. Der Upload wird angenommen und das Dokument beendet die Verarbeitung mit dem Status skipped.

Rate-Limits

API-Anfragen sind zur Sicherstellung fairer Nutzung limitiert:

60 Anfragen pro Minute pro API-Schlüssel
10 Dokument-Uploads pro Minute (POST /v1/documents)

Rate-Limit-Informationen sind in jeder Antwort über die Standard-Header RateLimit-* enthalten:

RateLimit-Limit: 60
RateLimit-Remaining: 55
RateLimit-Reset: 42

RateLimit-Reset gibt die Sekunden bis zum Zurücksetzen des aktuellen Zeitfensters an. Eine 429-Antwort enthält zusätzlich einen Retry-After-Header (Sekunden) und ein retryAfter-Feld im JSON-Body.

Rate-Limits handhaben

Wenn du eine 429-Antwort erhältst, warte die im Retry-After-Header angegebene Anzahl an Sekunden, bevor du es erneut versuchst. Implementiere exponentielles Backoff für Robustheit:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    if (response.status === 429) {
      const retryAfter = Number(response.headers.get("Retry-After") || 5);
      await new Promise(r => setTimeout(r, Math.max(retryAfter * 1000, 1000)));
      continue;
    }
    return response;
  }
  throw new Error("Rate limit exceeded after retries");
}

Häufige Fehlerszenarien

Fehler	Ursache	Lösung
"Invalid or missing API key"	Fehlender `Authorization`-Header oder fehlerhafter Schlüssel.	Prüfe Format und Header deines API-Schlüssels.
"Insufficient scope"	API-Schlüssel hat nicht die erforderliche Berechtigung.	Aktualisiere die Scopes unter Einstellungen > API-Schlüssel.
"Access denied to this space"	API-Schlüssel ist eingeschränkt und hat keinen Zugriff auf den angeforderten Space.	Füge den Space den erlaubten Spaces des Schlüssels hinzu oder verwende einen Schlüssel mit breiterem Zugriff.
"Document not found"	Dokument existiert nicht oder ist in einem nicht zugänglichen Space.	Prüfe die Dokument-ID und den Space-Zugriff deines Schlüssels.
"File content does not match any supported format"	Hochgeladene Datei-Bytes stimmen nicht mit PDF-, JPEG-, PNG-, TIFF- oder Office-Dokument-Signaturen überein.	Stelle sicher, dass du eine gültige Datei in einem unterstützten Format hochlädst.
"Content-Type mismatch"	Der Content-Type-Header stimmt nicht mit dem tatsächlichen Dateiinhalt überein.	Setze den richtigen Content-Type für deine Datei oder lass deinen HTTP-Client ihn automatisch erkennen.