Fehlercodes

Alle API-Fehler geben einen JSON-Body mit einer einheitlichen Struktur zurück. Prüfen Sie das Feld code für eine maschinenlesbare Identifikation und message für eine menschenlesbare Beschreibung des aufgetretenen Problems.

Struktur der Fehlerantwort

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "pipeline_id is required",
    "details": {
      "field": "pipeline_id"
    }
  }
}

Das Objekt details ist bei Validierungs- und Anreicherungsfehlern vorhanden und liefert feldspezifischen Kontext. Bei Fehlern, bei denen keine zusätzlichen Details verfügbar sind (z. B. INTERNAL_ERROR), ist es nicht enthalten.

HTTP-Statuscodes

Status	Code	Bedeutung
400	`BAD_REQUEST`	Der Anfrage-Body ist fehlerhaft oder Pflichtfelder fehlen
401	`UNAUTHORIZED`	Fehlende oder ungültige Authentifizierungsdaten
402	`PAYMENT_REQUIRED`	Unzureichendes Guthaben der Organisation
403	`FORBIDDEN`	Gültige Authentifizierung, aber unzureichende Berechtigungen oder Modul nicht aktiviert
404	`NOT_FOUND`	Ressource existiert nicht oder ist für Ihre Organisation nicht zugänglich
409	`CONFLICT`	Ressource existiert bereits (z. B. Mitglied bereits eingeladen)
410	`GONE`	Ressource wurde gelöscht oder Einladung ist abgelaufen
422	`UNPROCESSABLE_ENTITY`	Validierungsfehler (z. B. Anreicherung nicht abgeschlossen, fehlender Kontextschlüssel)
429	`TOO_MANY_REQUESTS`	Ratenlimit überschritten
500	`INTERNAL_ERROR`	Serverseitiger Fehler; mit exponentiellem Backoff erneut versuchen

Häufige Fehlerszenarien

Fehler	Status	Behebung
Dateianreicherung nicht abgeschlossen	422	`GET /v2/projects/{id}/files/{fileId}` pollen, bis `enrichmentStatus: "completed"`
Fehlender Pflicht-Kontextschlüssel	422	Die `requiredContextKeys` der Pipeline prüfen; fehlende Schlüssel zur Ausführungsanfrage hinzufügen
Modul nicht aktiviert	403	Crowdee kontaktieren, um `content_verification` oder `crowdsourcing` für Ihre Organisation zu aktivieren
Unzureichendes Guthaben	402	Über Einstellungen → Abrechnung aufladen; aktuelles Guthaben unter `GET /v2/organizations/{orgId}` prüfen
Einladung abgelaufen	410	Einladung erneut senden via `POST /v2/organizations/{orgId}/invite`
Ressource nicht gefunden	404	Bestätigen, dass die ID zu Ihrer Organisation gehört; IDs anderer Organisationen werden als nicht existent behandelt
Doppelte Einladung	409	Die E-Mail-Adresse hat bereits eine ausstehende Einladung oder ist bereits Mitglied

Beispiel: Anreicherungsfehler

Wenn Sie versuchen, eine Ausführung zu starten, bevor die Anreicherung abgeschlossen ist, erhalten Sie:

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "File enrichment is not complete",
    "details": {
      "fileId": "file_xyz789",
      "enrichmentStatus": "running"
    }
  }
}

Beispiel: Fehlender Kontextschlüssel

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Required context key 'claimed_source_url' is missing",
    "details": {
      "requiredKeys": ["claimed_source_url", "claimed_publication_date"],
      "providedKeys": ["claimed_publication_date"]
    }
  }
}

Wiederholungsversuche

Status	Wiederholung möglich?	Strategie
429	Ja	`Retry-After`-Sekunden abwarten, dann erneut versuchen
500	Ja	Exponentieller Backoff ab 1 Sekunde; nach 5 Versuchen aufgeben
502 / 503	Ja	Wie 500
400	Nein	Anfrage-Body korrigieren, bevor erneut versucht wird
401	Nein	Erneut authentifizieren; nicht mit denselben Anmeldedaten wiederholen
403	Nein	Berechtigungen prüfen oder Support kontaktieren
404	Nein	Ressourcen-ID verifizieren
422	Nein	Validierungsfehler beheben (z. B. auf den Abschluss der Anreicherung warten)

Der Header Retry-After ist in allen 429-Antworten enthalten und gibt die Anzahl der Sekunden bis zum Zurücksetzen des Ratenlimit-Fensters an. Verwenden Sie diesen Wert anstelle einer festen Verzögerung, um unnötige Wartezeiten zu vermeiden.