> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fehlerbehandlung & Antwortcodes

> Umfassende Anleitung zur Behandlung von API-Fehlern und Antwortcodes

## Einführung

Diese Anleitung deckt alle möglichen Antwortcodes, Fehlerformate und Best Practices für die Behandlung von Fehlern bei der Integration mit der Lovi API ab.

## 📊 HTTP-Statuscodes

### Erfolgreiche Antworten

#### 200 OK - Anfrage erfolgreich

**Benachrichtigung verarbeitet:**

```json theme={null}
{
  "success": true,
  "message": "Benachrichtigung erfolgreich in Warteschlange eingereiht",
  "notification_id": "uuid-notification-123",
  "scheduled_time": "2024-12-25T10:30:00Z"
}
```

**Templates abgerufen:**

```json theme={null}
{
  "templates": [
    {
      "id": "template_001",
      "name": "welcome_user",
      "status": "approved"
    }
  ],
  "total": 1
}
```

**Template erstellt:**

```json theme={null}
{
  "success": true,
  "message": "Template erfolgreich erstellt",
  "template": {
    "id": "new_template_123",
    "name": "order_confirmation",
    "status": "pending"
  }
}
```

***

### Client-Fehlerantworten (4xx)

#### 400 Bad Request - Ungültige Parameter

**Erforderliches Feld fehlt:**

```json theme={null}
{
  "error": "validation_failed",
  "message": "Erforderliches Feld fehlt",
  "details": {
    "field": "contact.number",
    "reason": "Dieses Feld ist erforderlich"
  },
  "request_id": "req_123456789"
}
```

**Ungültiges Parameterformat:**

```json theme={null}
{
  "error": "validation_failed",
  "message": "Ungültiges Parameterformat",
  "details": {
    "field": "datetime_sending",
    "provided": "25-12-2024",
    "expected_format": "ISO 8601 (YYYY-MM-DDTHH:MM:SS)",
    "example": "2024-12-25T10:30:00"
  },
  "request_id": "req_123456790"
}
```

#### 401 Unauthorized - Authentifizierung fehlgeschlagen

**Ungültiger Zugriffsschlüssel:**

```json theme={null}
{
  "error": "unauthorized",
  "message": "Ungültiger oder abgelaufener Zugriffsschlüssel",
  "details": {
    "reason": "Der bereitgestellte access_key ist ungültig oder wurde widerrufen"
  },
  "request_id": "req_123456793"
}
```

#### 403 Forbidden - Zugriff verweigert

**Unzureichende Berechtigungen:**

```json theme={null}
{
  "error": "forbidden",
  "message": "Unzureichende Berechtigungen für diese Ressource",
  "details": {
    "reason": "Ihr API-Schlüssel hat keine Berechtigung zum Erstellen von Templates"
  },
  "request_id": "req_123456795"
}
```

#### 404 Not Found - Ressource nicht gefunden

**Template nicht gefunden:**

```json theme={null}
{
  "error": "template_not_found",
  "message": "Template 'welcome_user' nicht gefunden oder nicht genehmigt",
  "details": {
    "template_name": "welcome_user",
    "language": "de_DE",
    "suggestion": "Überprüfen Sie den Template-Namen und Genehmigungsstatus"
  },
  "request_id": "req_123456797"
}
```

#### 422 Unprocessable Entity - Geschäftslogik-Fehler

**Template nicht genehmigt:**

```json theme={null}
{
  "error": "template_not_approved",
  "message": "Template ist nicht im genehmigten Status",
  "details": {
    "template_name": "pending_template",
    "current_status": "pending",
    "required_status": "approved"
  },
  "request_id": "req_123456799"
}
```

#### 429 Too Many Requests - Ratenlimit überschritten

**Ratenlimit erreicht:**

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Zu viele Anfragen. Versuchen Sie es in 60 Sekunden erneut",
  "details": {
    "limit": 100,
    "window": "1 Stunde",
    "reset_time": "2024-12-20T16:30:00Z"
  },
  "retry_after": 60,
  "request_id": "req_123456801"
}
```

***

### Server-Fehlerantworten (5xx)

#### 500 Internal Server Error

**Allgemeiner Serverfehler:**

```json theme={null}
{
  "error": "internal_error",
  "message": "Ein unerwarteter Fehler ist aufgetreten",
  "details": {
    "reason": "Interner Serverfehler"
  },
  "request_id": "req_123456803"
}
```

#### 502 Bad Gateway

**Upstream-Service-Fehler:**

```json theme={null}
{
  "error": "service_unavailable",
  "message": "WhatsApp-Service vorübergehend nicht verfügbar",
  "details": {
    "service": "whatsapp_gateway",
    "estimated_recovery": "2024-12-20T16:00:00Z"
  },
  "request_id": "req_123456804"
}
```

#### 503 Service Unavailable

**Wartungsmodus:**

```json theme={null}
{
  "error": "service_unavailable",
  "message": "Service vorübergehend für Wartung nicht verfügbar",
  "details": {
    "maintenance_window": "2024-12-20T02:00:00Z to 2024-12-20T04:00:00Z"
  },
  "request_id": "req_123456805"
}
```

***

## 🔄 Retry-Strategien

### Empfohlene Retry-Logik

| Statuscode      | Aktion                                        | Retry-Strategie                          |
| --------------- | --------------------------------------------- | ---------------------------------------- |
| `400, 404, 422` | ❌ **Nicht wiederholen**                       | Anfrage korrigieren und erneut versuchen |
| `401, 403`      | ❌ **Nicht wiederholen**                       | Authentifizierung aktualisieren          |
| `429`           | ⏰ **Mit Backoff wiederholen**                 | `retry_after`-Header verwenden           |
| `500, 502, 503` | 🔄 **Mit exponentiellem Backoff wiederholen** | Max 3 Versuche                           |

***

## 📝 Best Practices

### Checklist für Fehlerbehandlung

✅ **Pre-Request-Validierung**

* Telefonnummernformat validieren
* Erforderliche Felder überprüfen
* Datetime-Format validieren
* Template-Existenz überprüfen

✅ **Anfrage-Monitoring**

* Alle API-Anfragen protokollieren
* request\_id in Logs einschließen
* Antwortzeiten überwachen
* Fehlerraten verfolgen

✅ **Fehlerwiederherstellung**

* Angemessene Retry-Logik implementieren
* Authentifizierungstokens cachen
* Ratenlimits elegant behandeln
* Bedeutungsvolle Fehlermeldungen an Benutzer liefern

✅ **Benutzererfahrung**

* Benutzerfreundliche Fehlermeldungen anzeigen
* Umsetzbare Rückmeldung bereitstellen
* Interne Fehlerdetails nicht freigeben
* Alternativen anbieten, wenn möglich

Denken Sie daran, immer die `request_id` einzuschließen, wenn Sie sich an den Support wenden, für eine schnellere Fehlerbehebung.