Fehlerbehandlung

Verstehen Sie die Fehlercodes und wie Sie damit umgehen können.

HTTP Status Codes

Die API verwendet Standard-HTTP-Statuscodes:

2xx - Erfolg
Code Name Bedeutung
200 OK Request erfolgreich verarbeitet
201 Created Ressource erfolgreich erstellt
204 No Content Request erfolgreich, keine Daten zurückgegeben (z.B. bei DELETE)
4xx - Client-Fehler
Code Name Bedeutung
400 Bad Request Ungültige Request-Parameter
401 Unauthorized Authentifizierung fehlgeschlagen oder fehlt
403 Forbidden Keine Berechtigung für diese Ressource
404 Not Found Ressource nicht gefunden
422 Unprocessable Entity Validierungsfehler
429 Too Many Requests Rate Limit überschritten
5xx - Server-Fehler
Code Name Bedeutung
500 Internal Server Error Unerwarteter Serverfehler
503 Service Unavailable Server vorübergehend nicht verfügbar

Fehler-Response Format

Allgemeines Fehler-Format
{
  "success": false,
  "message": "Kurze Fehlerbeschreibung",
  "errors": {
    "field_name": [
      "Detaillierte Fehlermeldung für dieses Feld"
    ]
  }
}
Beispiel: Validierungsfehler (422)
{
  "success": false,
  "message": "Die angegebenen Daten sind ungültig.",
  "errors": {
    "email": [
      "Die E-Mail-Adresse muss eine gültige E-Mail-Adresse sein."
    ],
    "password": [
      "Das Passwort muss mindestens 8 Zeichen lang sein."
    ]
  }
}
Beispiel: Authentifizierungsfehler (401)
{
  "message": "Unauthenticated."
}
Beispiel: Nicht gefunden (404)
{
  "success": false,
  "message": "Ressource nicht gefunden"
}
Beispiel: Rate Limit (429)
{
  "message": "Too Many Attempts.",
  "retry_after": 60
}

Häufige Fehler & Lösungen

Ursache:

  • Authorization Header fehlt
  • Token ist ungültig oder abgelaufen
  • Falsches Token-Format

Lösung:

# Korrektes Format:
Authorization: Bearer YOUR_TOKEN

# NICHT:
Authorization: YOUR_TOKEN
Authorization: Token YOUR_TOKEN

Ursache:

  • Erforderliche Felder fehlen
  • Datenformat ist falsch
  • Validierungsregeln nicht erfüllt

Lösung:

Prüfen Sie das errors Objekt in der Response für Details:

if (response.status === 422) {
    const errors = await response.json();
    console.log(errors.errors); // Zeigt alle Validierungsfehler
}

Ursache:

  • Zu viele Requests in kurzer Zeit
  • Limit: 60 Requests/Minute (authentifiziert)
  • Limit: 10 Requests/Minute (nicht authentifiziert)

Lösung:

// Prüfe Rate Limit Headers
const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');

if (response.status === 429) {
    const waitTime = reset - Date.now() / 1000;
    console.log(`Warte ${waitTime} Sekunden`);
}

Ursache:

  • Falsche URL/Endpoint
  • ID existiert nicht
  • Ressource wurde gelöscht

Lösung:

  • Prüfen Sie die URL auf Tippfehler
  • Verwenden Sie GET-Requests um zu prüfen ob die Ressource existiert
  • Prüfen Sie die Route-Übersicht

Ursache:

  • Accept Header fehlt bei API-Requests

Lösung:

# Fügen Sie immer diesen Header hinzu:
Accept: application/json

Best Practices

1. Immer Fehler abfangen
try {
    const response = await fetch(url, options);
    
    if (!response.ok) {
        const error = await response.json();
        console.error('API Error:', error);
        // Zeige Fehler dem Benutzer
    }
    
    const data = await response.json();
    // Verarbeite erfolgreiche Response
    
} catch (error) {
    console.error('Network Error:', error);
    // Netzwerkfehler behandeln
}
2. Status Code prüfen
switch (response.status) {
    case 200:
        // Erfolg
        break;
    case 401:
        // Zum Login weiterleiten
        break;
    case 404:
        // Ressource nicht gefunden
        break;
    case 422:
        // Validierungsfehler anzeigen
        break;
    case 429:
        // Rate Limit - warten und wiederholen
        break;
    default:
        // Allgemeiner Fehler
}
3. Retry-Logik implementieren
async function apiRequest(url, options, retries = 3) {
    for (let i = 0; i < retries; i++) {
        try {
            const response = await fetch(url, options);
            
            if (response.status === 429) {
                // Rate Limit - warte und versuche erneut
                await new Promise(r => setTimeout(r, 1000 * (i + 1)));
                continue;
            }
            
            return response;
        } catch (error) {
            if (i === retries - 1) throw error;
            await new Promise(r => setTimeout(r, 1000 * (i + 1)));
        }
    }
}
4. Benutzerfreundliche Fehlermeldungen
function showError(error) {
    const messages = {
        401: 'Bitte melden Sie sich an',
        403: 'Sie haben keine Berechtigung für diese Aktion',
        404: 'Die Ressource wurde nicht gefunden',
        422: 'Bitte überprüfen Sie Ihre Eingaben',
        429: 'Zu viele Anfragen. Bitte warten Sie einen Moment',
        500: 'Ein Serverfehler ist aufgetreten. Bitte versuchen Sie es später erneut'
    };
    
    return messages[error.status] || 'Ein unbekannter Fehler ist aufgetreten';
}

Debugging-Tipps

1. Request & Response loggen
console.log('Request:', {
    url,
    method: options.method,
    headers: options.headers,
    body: options.body
});

console.log('Response:', {
    status: response.status,
    headers: Object.fromEntries(response.headers),
    body: await response.clone().json()
});
2. Browser DevTools nutzen
  • Network-Tab: Alle Requests und Responses inspizieren
  • Console: Fehler und Logs anzeigen
  • Preserve Log aktivieren für vollständigen Request-Verlauf
3. cURL-Befehle testen

Testen Sie Endpoints direkt im Terminal:

curl -v -X GET https://kerzenheim.gruppen-admin.de/api/user \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Das -v Flag zeigt alle Headers und Details.