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

# Server-Ereignisse prüfen und debuggen

> Prüfen, ob Ihre serverseitigen Konversionsereignisse ankommen, richtig zugeordnet werden und in den Berichten auftauchen — samt Lösungen für häufige Fehler.

## Schritt 1: Ein Testereignis senden

Senden Sie ein einzelnes Testereignis mit einer bekannten `event_id`, damit Sie es nachverfolgen können:

```bash theme={null}
curl -X POST "https://track.scanova.io/server-events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "site_id": "YOUR_SITE_ID",
    "event_name": "test_event",
    "event_id": "00000000-0000-0000-0000-000000000001",
    "scan_session_id": "00000000-0000-0000-0000-000000000002",
    "properties": { "test": true }
  }'
```

Eine erfolgreiche Antwort sieht so aus:

```json theme={null}
{
  "event_id": "00000000-0000-0000-0000-000000000001",
  "status": "accepted"
}
```

## Schritt 2: Prüfen, ob es im Dashboard erscheint

1. Öffnen Sie das Scanova-Dashboard
2. Gehen Sie zu **Analysen → Konversionsverfolgung**
3. Öffnen Sie die Tracking-Website
4. Ihr `test_event` sollte innerhalb von 30–60 Sekunden erscheinen

## Schritt 3: Die Dublettenerkennung testen

Senden Sie dieselbe Anfrage mit derselben `event_id` erneut:

```bash theme={null}
# Same request again
curl -X POST "https://track.scanova.io/server-events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "site_id": "YOUR_SITE_ID",
    "event_name": "test_event",
    "event_id": "00000000-0000-0000-0000-000000000001",
    "scan_session_id": "00000000-0000-0000-0000-000000000002"
  }'
```

Die zweite Anfrage liefert `200`, das Ereignis wird jedoch als Dublette markiert und nicht in die Konversionszahlen aufgenommen. Prüfen Sie, dass die Ereigniszahl in den Berichten nicht gestiegen ist.

***

## Häufige Fehler und ihre Behebung

### `401` — Fehlender API-Schlüssel

Der Header `X-API-Key` fehlt in der Anfrage.

```bash theme={null}
# Wrong — missing header
curl -X POST "https://track.scanova.io/server-events" -d '{...}'

# Correct
curl -X POST "https://track.scanova.io/server-events" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{...}'
```

### `403` — Ungültiger Schlüssel oder nicht berechtigte Website

Entweder ist der API-Schlüssel ungültig oder widerrufen, oder die `site_id` in den Nutzdaten gehört nicht zu der Website des Schlüssels. Prüfen Sie:

* dass der Schlüssel korrekt kopiert wurde (keine Leerzeichen oder Zeilenumbrüche am Ende)
* dass die `site_id` im Anfragetext genau der Website entspricht, die den Schlüssel erzeugt hat
* dass der Schlüssel im Dashboard nicht widerrufen wurde

### `422` — Validierungsfehler

Die Nutzdaten haben die Schemaprüfung nicht bestanden. Der Antworttext enthält Einzelheiten:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "scan_session_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

Häufige Ursachen:

* Ein Pflichtfeld fehlt (`site_id`, `event_name` oder `scan_session_id`)
* `scan_session_id` liegt nicht im gültigen UUID-Format vor
* `conversion_value.currency` ist kein dreistelliger ISO-Code
* Das Objekt `properties` ist größer als 10 KB
* Eine E-Mail-Adresse im Klartext in `properties` (nutzen Sie stattdessen `user_identifiers.email_hash`)

### `429` — Ratengrenze überschritten

Sie senden mehr als 1.000 Ereignisse pro Minute und API-Schlüssel. Warten Sie ab und wiederholen Sie:

* Prüfen Sie den Header `Retry-After` in der Antwort
* Fassen Sie mit dem Batch-Endpunkt (`POST /server-events/batch`) mehrere Ereignisse zu weniger Anfragen zusammen

### Ereignis zugestellt, aber nicht in den Berichten

* Warten Sie 60 Sekunden — die Verarbeitung dauert einen Moment
* Prüfen Sie, ob die `site_id` in Ihren Nutzdaten zu der Tracking-Website passt, die Sie im Dashboard ansehen
* Prüfen Sie, ob die `scan_session_id` eine gültige UUID ist — ein ungültiges Format wird mit `422` abgelehnt
* Vergewissern Sie sich, dass die gesendete `scan_session_id` zu einer echten Scan-Sitzung aus einem QR-Code-Scan gehört und keine Test-UUID ist — Ereignisse mit nicht auflösbaren Sitzungen werden nicht zugeordnet und erscheinen möglicherweise nicht in den Berichten