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

# Erreurs et limites de débit

> Codes de statut HTTP, format des réponses d'erreur, limites de débit et conseils de gestion des erreurs pour les API du suivi des conversions Scanova.

## Codes de statut HTTP

| Code                  | Signification                                                             | Action                                                          |
| --------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `200`                 | Événement accepté                                                         | Rien à faire                                                    |
| `400`                 | Requête incorrecte — champ manquant, format invalide ou `site_id` inactif | Corrigez le contenu de la requête                               |
| `401`                 | En-tête `X-API-Key` manquant                                              | Ajoutez l'en-tête `X-API-Key`                                   |
| `403`                 | Clé invalide, clé révoquée, ou `site_id` et clé qui ne correspondent pas  | Vérifiez votre clé d'API et le `site_id`                        |
| `413`                 | Contenu trop volumineux                                                   | Réduisez sa taille ou découpez-le en lots plus petits           |
| `422`                 | Erreur de validation — le détail figure dans le corps de la réponse       | Corrigez l'erreur du champ signalé                              |
| `429`                 | Limite de débit dépassée                                                  | Patientez et relancez après la durée de l'en-tête `Retry-After` |
| `500` / `502` / `503` | Erreur serveur                                                            | Relancez avec un délai exponentiel                              |

## Format de la réponse d'erreur

Toutes les réponses d'erreur renvoient un corps JSON détaillé :

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

Pour les erreurs `400` avec un message unique :

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

## Limites de débit

| Point de terminaison               | Limite               | Portée         |
| ---------------------------------- | -------------------- | -------------- |
| `POST /ct` (événements navigateur) | 100 requêtes / min   | Par adresse IP |
| `POST /collect/batch`              | 100 requêtes / min   | Par adresse IP |
| `POST /server-events`              | 1 000 requêtes / min | Par clé d'API  |
| `POST /server-events/batch`        | 1 000 requêtes / min | Par clé d'API  |

<Note>
  De courtes pointes au-delà de la limite passent grâce à une petite marge de tolérance. Concevez vos clients pour qu'ils patientent après un `429` plutôt que de compter sur cette marge.
</Note>

## Schéma de gestion des erreurs

### Pour les événements serveur

```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)}`);
}
```

### Logique de relance

Ne relancez que sur les erreurs passagères. Sur les erreurs permanentes, arrêtez immédiatement.

| Relancer ?                         | Codes de statut                                         |
| ---------------------------------- | ------------------------------------------------------- |
| Oui — relance avec délai croissant | `429`, `500`, `502`, `503`, `504`, délai réseau dépassé |
| Non — corrigez la requête          | `400`, `401`, `403`, `413`, `422`                       |

Voir [Idempotence et relances](/fr/conversion-tracking/server/idempotency-retries) pour une implémentation complète avec délai exponentiel.

## Causes fréquentes de `422`

| Erreur                               | Correction                                                                        |
| ------------------------------------ | --------------------------------------------------------------------------------- |
| Format de `scan_session_id` invalide | Ce doit être un UUID valide (par exemple `7ad26d4f-3181-4ef8-b6ca-b8f59499dd43`)  |
| `event_name` manquant                | Obligatoire pour les événements serveur                                           |
| `conversion_value.currency` invalide | Ce doit être un code ISO 4217 à trois lettres (par exemple `USD`, `EUR` ou `GBP`) |
| `properties` trop volumineux         | Restez sous 10 Ko                                                                 |
| E-mail en clair dans `properties`    | Utilisez plutôt `user_identifiers.email_hash` avec un hachage SHA-256             |