> ## 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.

# Fehler & Ratengrenzen

> HTTP-Statuscodes, Aufbau der Fehlerantworten, Ratengrenzen und Hinweise zum Umgang mit Fehlern in sämtlichen APIs der Konversionsverfolgung von Scanova.

## HTTP-Statuscodes

| Code                  | Bedeutung                                                                                  | Vorgehen                                                         |
| --------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| `200`                 | Ereignis angenommen                                                                        | Nichts zu tun                                                    |
| `400`                 | Fehlerhafte Anfrage — fehlendes Feld, ungültiges Format oder inaktive `site_id`            | Nutzdaten der Anfrage korrigieren                                |
| `401`                 | Der Header `X-API-Key` fehlt                                                               | Den Header `X-API-Key` ergänzen                                  |
| `403`                 | Ungültiger oder widerrufener Schlüssel, oder `site_id` und Schlüssel passen nicht zusammen | API-Schlüssel und `site_id` prüfen                               |
| `413`                 | Nutzdaten zu groß                                                                          | Nutzdaten verkleinern oder in kleinere Stapel aufteilen          |
| `422`                 | Validierungsfehler — Einzelheiten stehen im Antworttext                                    | Den genannten Feldfehler beheben                                 |
| `429`                 | Ratengrenze überschritten                                                                  | Abwarten und nach dem Wert im Header `Retry-After` erneut senden |
| `500` / `502` / `503` | Serverfehler                                                                               | Mit exponentiell wachsender Wartezeit wiederholen                |

## Aufbau der Fehlerantwort

Alle Fehlerantworten enthalten einen JSON-Text mit Einzelheiten:

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

Bei `400`-Fehlern mit nur einer Meldung:

```json theme={null}
{
  "detail": "site_id not found or inactive"
}
```

## Ratengrenzen

| Endpunkt                        | Grenze                    | Gilt je       |
| ------------------------------- | ------------------------- | ------------- |
| `POST /ct` (Browser-Ereignisse) | 100 Anfragen pro Minute   | IP-Adresse    |
| `POST /collect/batch`           | 100 Anfragen pro Minute   | IP-Adresse    |
| `POST /server-events`           | 1.000 Anfragen pro Minute | API-Schlüssel |
| `POST /server-events/batch`     | 1.000 Anfragen pro Minute | API-Schlüssel |

<Note>
  Kurze Spitzen über der Grenze fängt ein kleiner Kulanzbereich ab. Legen Sie Ihre Clients so aus, dass sie bei `429` abwarten, statt sich auf diese Toleranz zu verlassen.
</Note>

## Muster für die Fehlerbehandlung

### Für Server-Ereignisse

```javascript theme={null}
async function sendEvent(payload) {
  const response = await fetch('https://track.scanova.io/server-events', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.SCANOVA_API_KEY,
    },
    body: JSON.stringify(payload),
  });

  if (response.ok) return await response.json();

  const error = await response.json().catch(() => null);

  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') ?? '60', 10);
    throw new RetryableError(`Rate limited — retry after ${retryAfter}s`, retryAfter);
  }

  if (response.status >= 500) {
    throw new RetryableError(`Server error ${response.status}`);
  }

  // 400, 401, 403, 422 — do not retry, fix the request
  throw new PermanentError(`Request failed ${response.status}: ${JSON.stringify(error)}`);
}
```

### Logik für Wiederholungen

Wiederholen Sie nur bei vorübergehenden Fehlern. Bei dauerhaften Fehlern brechen Sie sofort ab.

| Wiederholen?                              | Statuscodes                                         |
| ----------------------------------------- | --------------------------------------------------- |
| Ja — mit wachsender Wartezeit wiederholen | `429`, `500`, `502`, `503`, `504`, Netzwerk-Timeout |
| Nein — die Anfrage korrigieren            | `400`, `401`, `403`, `413`, `422`                   |

Eine vollständige Umsetzung mit exponentiell wachsender Wartezeit finden Sie unter [Idempotenz & Wiederholungen](/de/conversion-tracking/server/idempotency-retries).

## Häufige Ursachen für `422`

| Fehler                                      | Behebung                                                                      |
| ------------------------------------------- | ----------------------------------------------------------------------------- |
| `scan_session_id` hat ein ungültiges Format | Es muss eine gültige UUID sein (z. B. `7ad26d4f-3181-4ef8-b6ca-b8f59499dd43`) |
| `event_name` fehlt                          | Bei Server-Ereignissen erforderlich                                           |
| `conversion_value.currency` ist ungültig    | Es muss ein dreistelliger ISO-4217-Code sein (z. B. `USD`, `EUR`, `GBP`)      |
| `properties` ist zu groß                    | Unter 10 KB bleiben                                                           |
| E-Mail-Adresse im Klartext in `properties`  | Stattdessen `user_identifiers.email_hash` mit einem SHA-256-Hash nutzen       |