## Portée

Pour les requêtes dont le chemin commence par **`/api/`**, les exceptions non gérées et les erreurs HTTP courantes sont formatées en JSON avec la structure ci-dessous (y compris **404** « route introuvable » ou modèle introuvable).

## Structure d’une erreur

```json
{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Les données envoyées sont invalides.",
    "details": {
      "domain": ["The domain field is required."]
    }
  }
}
```

Le champ `details` n’est présent que lorsqu’il y a des informations supplémentaires (souvent erreurs de validation par champ).

## Codes HTTP usuels

| Code | Cas typique |
|------|-------------|
| `401` | Token manquant ou invalide (`unauthenticated`) |
| `403` | Permission insuffisante (`forbidden`) ou token sandbox en écriture (`sandbox_read_only`) |
| `404` | Ressource introuvable ou non autorisée (`not_found`) |
| `422` | Règle métier / validation (`validation_error`, `invalid_state`, `no_reseller_service`, etc.) |
| `429` | Limite de débit |
| `500` | Erreur serveur (`server_error`, hors mode debug) |
| `503` | Service externe indisponible (`whm_unavailable`, `payment_unavailable`, …) |

## Codes `error.code` renvoyés par les contrôleurs v1

Les contrôleurs utilisent des codes **snake_case** cohérents avec le JSON métier :

| Code | HTTP | Signification |
|------|------|---------------|
| `forbidden` | 403 | Scope Sanctum manquant (`Missing scope: …`) ou action interdite |
| `not_found` | 404 | Ressource absente ou n’appartenant pas à l’utilisateur |
| `unauthenticated` | 401 | Non authentifié (handler global) |
| `validation_error` | 422 | Erreur de validation ; détails dans `error.details` |
| `sandbox_read_only` | 403 | Clé `kh_test_` : pas d’écriture |
| `invalid_state` | 422 | État incompatible (ex. ticket fermé, facture non payable) |
| `no_reseller_service` | 422 | Pas de service revendeur actif |
| `whm_unavailable` | 503 | WHM non configuré |
| `whm_error` | 422 / 503 | Erreur retournée par l’API WHM |
| `payment_unavailable` | 503 | Passerelle de paiement non configurée |
| `payment_init_failed` | 422 | Échec d’initialisation NotchPay |
| `dns_error` | 422 | Erreur DNS / registrar |

Les réponses **`success: true`** des endpoints métier utilisent leurs propres codes dans `data` lorsque pertinent (ex. `reason_code` pour la disponibilité domaine).

## Erreurs globales (handler)

| Code | HTTP | Quand |
|------|------|--------|
| `http_error` | variable | Exception HTTP générique |
| `server_error` | 500 | Erreur non prévue (hors `APP_DEBUG`) |

## Bonnes pratiques

```php
$json = $response->json();
if (!($json['success'] ?? false)) {
    $code = $json['error']['code'] ?? 'unknown';
    // journaliser, retry, alerter…
}
```

Pour la validation, parcourez `error.details` (tableau associatif champ → liste de messages).