# Erreurs et limites

## Format des erreurs

Toutes les erreurs ont la même forme :

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Crédits insuffisants pour cet envoi.",
    "details": { "credits_available": 0, "credits_required": 2, "documents_count": 2 }
  }
}
```

Votre code doit réagir sur `code`. `message` est une phrase en français pour un humain : sa formulation peut changer. `details` n'est présent que lorsqu'il apporte une information.

## Codes

| Statut HTTP | `code` | Signification |
|---|---|---|
| 401 | `unauthorized` | Clé absente, invalide ou révoquée. |
| 402 | `insufficient_credits` | Solde insuffisant pour l'envoi. Rien n'a été débité. |
| 404 | `not_found` | Ressource ou route inconnue, ou qui appartient à un autre compte. |
| 405 | `method_not_allowed` | Méthode HTTP non prévue sur cette route. |
| 409 | `not_available_in_test_mode` | Fonction indisponible avec une clé test (rapport PDF). |
| 413 | `validation_failed` | Requête trop volumineuse. |
| 422 | `validation_failed` | Paramètres invalides. `details.fields` liste les champs en cause. |
| 429 | `rate_limited` | Trop de requêtes. Attendez le nombre de secondes indiqué par `Retry-After`. |
| 500 | `internal_error` | Erreur de notre côté. Réessayez ; si elle persiste, écrivez à contact@france-verification.com. |

La liste des codes peut s'allonger ; un code ne change jamais de sens.

## Limite de débit

60 requêtes par minute et par clé. Chaque réponse porte :

| En-tête | Contenu |
|---|---|
| `X-RateLimit-Limit` | 60 |
| `X-RateLimit-Remaining` | Requêtes restantes dans la minute. |
| `Retry-After` | En cas de `429`, secondes à attendre. |

Un envoi peut contenir jusqu'à `max_files_per_submission` fichiers : pour un gros volume, regroupez les fichiers plutôt que de multiplier les appels.

## Rejouer sans risque

Une requête interrompue (coupure réseau, délai dépassé) peut avoir été traitée ou non. Envoyez vos `POST /submissions` avec un en-tête `Idempotency-Key` : en cas de doute, renvoyez exactement la même requête avec la même clé, vous obtiendrez l'envoi déjà créé sans double débit. La clé reste réservée 24 heures.