Codes d'erreur - KennHosting

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

{
  "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

$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).

​Portée

​Structure d’une erreur

​Codes HTTP usuels

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

​Erreurs globales (handler)