Fehlercodes

Verstehen Sie API-Fehlerantworten und wie Sie diese behandeln.

Übersicht

Die API gibt standardisierte Fehlerantworten mit spezifischen Fehlercodes zurück, um Ihnen zu helfen, Probleme schnell zu identifizieren und zu beheben.

Format der Fehlerantwort

Alle Fehlerantworten folgen dieser Struktur:

{
  "status": "error",
  "error": {
    "code": "AUTH_1001",
    "message": "Fehlende Authentifizierungsdaten",
    "details": "Die Felder 'username' und 'password' sind beide erforderlich",
    "timestamp": "2025-12-22T10:30:00Z"
  }
}

Feld	Typ	Beschreibung
`status`	string	Immer "error" bei Fehlerantworten
`error.code`	string	Eindeutiger Fehlerbezeichner
`error.message`	string	Lesbare Fehlermeldung
`error.details`	string	Zusätzlicher Kontext (optional)
`error.timestamp`	string	ISO 8601 Zeitstempel

Authentifizierungsfehler (1000-1099)

Fehler im Zusammenhang mit Anmeldedaten und Authentifizierung.

Code	HTTP	Meldung	Lösung
`AUTH_1001`	401	Fehlende Authentifizierungsdaten	Fügen Sie sowohl Benutzername als auch Passwort in die Anfrage ein
`AUTH_1002`	401	Ungültiger Benutzername oder Passwort	Überprüfen Sie, ob die Anmeldedaten korrekt sind
`AUTH_1003`	403	Konto vorübergehend gesperrt	Warten Sie, bevor Sie es erneut versuchen, oder kontaktieren Sie den Support

Kontingentfehler (1100-1199)

Fehler im Zusammenhang mit API-Kontingent und Nutzungslimits.

Code	HTTP	Meldung	Lösung
`QUOTA_1101`	403	Unzureichendes API-Kontingent	Kaufen Sie mehr Credits oder überprüfen Sie das Kontingent
`QUOTA_1102`	429	API-Kontingent überschritten	Warten Sie auf die Kontingenterneuerung oder upgraden Sie Ihren Plan

Validierungsfehler (2000-2099)

Fehler im Zusammenhang mit Anforderungsvalidierung und Eingabedaten.

Code	HTTP	Meldung	Lösung
`VAL_2001`	400	Keine Datei hochgeladen	Fügen Sie eine Datei in die Anfrage ein
`VAL_2002`	400	Ungültiges Dateiformat	Verwenden Sie unterstützte Formate: PDF, PNG, JPG, WEBP
`VAL_2003`	400	Mehrere PDF-Dateien nicht erlaubt	Laden Sie eine einzelne PDF oder mehrere Bilder hoch
`VAL_2004`	400	PDF und Bilder können nicht gemischt werden	Laden Sie entweder PDF oder Bilder hoch, nicht beides
`VAL_2005`	400	Nicht unterstützter Sprachcode	Verwenden Sie einen unterstützten Sprachcode

Verarbeitungsfehler (3000-3099)

Fehler während der Dokumentenverarbeitung und KI-Analyse.

Code	HTTP	Meldung	Lösung
`PROC_3001`	500	Dokumentenverarbeitung fehlgeschlagen	Überprüfen Sie die Bildqualität, versuchen Sie die Anfrage erneut
`PROC_3002`	500	Metadatenextraktion fehlgeschlagen	Stellen Sie sicher, dass das Dokument lesbaren Text enthält
`PROC_3003`	500	Parameterextraktion fehlgeschlagen	Überprüfen Sie, ob das Bluttestformat erkennbar ist
`PROC_3004`	500	Interpretationsgenerierung fehlgeschlagen	Versuchen Sie die Anfrage erneut
`PROC_3006`	504	Verarbeitungs-Timeout	Reduzieren Sie die Dateigröße oder teilen Sie in mehrere Anfragen auf
`PROC_3007`	500	Analyse nach mehreren Versuchen fehlgeschlagen	Warten Sie und versuchen Sie es erneut, oder kontaktieren Sie den Support

Serverfehler (5000-5099)

Interne Serverfehler und Probleme mit der Dienstverfügbarkeit.

Code	HTTP	Meldung	Lösung
`SRV_5001`	500	Interner Serverfehler	Versuchen Sie die Anfrage erneut, kontaktieren Sie den Support bei anhaltenden Problemen
`SRV_5002`	503	Dienst vorübergehend nicht verfügbar	Warten Sie und versuchen Sie es mit exponentiellem Backoff erneut

Best Practices für die Fehlerbehandlung

Empfehlungen

Prüfen Sie immer das status-Feld - Erfolgreiche Antworten haben "status": "success"
Implementieren Sie Retry-Logik für vorübergehende Fehler (5xx) mit exponentiellem Backoff
Protokollieren Sie Fehlercodes für Debugging und Überwachung
Zeigen Sie benutzerfreundliche Meldungen basierend auf Fehlercodes an
Verwenden Sie Sandbox-Endpunkte zum Testen der Fehlerbehandlung

Beispiel für Fehlerbehandlung (JavaScript)

async function analyzeBloodTest(file) {
  try {
    const response = await fetch(API_URL, {
      method: 'POST',
      body: formData
    });

    const data = await response.json();

    if (data.status === 'error') {
      const errorCode = data.error.code;

      switch (true) {
        case errorCode.startsWith('AUTH_'):
          throw new Error('Authentifizierung fehlgeschlagen. Überprüfen Sie Ihre Anmeldedaten.');
        case errorCode.startsWith('QUOTA_'):
          throw new Error('Kontingent überschritten. Bitte upgraden Sie Ihren Plan.');
        case errorCode.startsWith('VAL_'):
          throw new Error('Ungültige Anfrage: ' + data.error.message);
        case errorCode.startsWith('PROC_'):
          // Wiederholung bei Verarbeitungsfehlern
          return retryRequest(file);
        default:
          throw new Error('Ein Fehler ist aufgetreten. Bitte versuchen Sie es erneut.');
      }
    }

    return data.data;
  } catch (error) {
    console.error('API-Fehler:', error);
    throw error;
  }
}