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 (Standardlimits sind 100/Min und 1.000/Stunde pro API-Schlüssel; einige Endpunkte können strengere Limits haben).
500	Interner Serverfehler - auf unserer Seite ist etwas schiefgelaufen.

Rate-Limits

API-Anfragen sind zur Sicherstellung fairer Nutzung limitiert:

• 100 Anfragen pro Minute pro API-Schlüssel
• 1.000 Anfragen pro Stunde pro API-Schlüssel

Rate-Limit-Header sind in jeder Antwort enthalten:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709740800

Rate-Limits handhaben

Wenn du eine 429-Antwort erhältst, warte bis zum Zeitpunkt, der durch X-RateLimit-Reset (Unix-Zeitstempel) angegeben ist, 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 resetTime = response.headers.get("X-RateLimit-Reset");
      const waitMs = (resetTime * 1000) - Date.now() + 1000;
      await new Promise(r => setTimeout(r, Math.max(waitMs, 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- oder TIFF-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.