Erreurs

Disponible

Fonctionnalité déployée et prise en charge. Les champs et commandes décrits ici sont stables au sein de la version v1alpha1.

Toutes les erreurs de l'API ont la même forme, 415 et 429 compris :

{"error": "forbidden"}

Le message est court, stable et sans détail interne : il ne nomme ni un service, ni un chemin, ni une adresse. Pour comprendre une erreur, combinez le code HTTP, le message et le contexte de la requête.

Codes

Code	Message typique	Cause	Que faire
400	bad request, invalid …, … required	Corps JSON invalide, champ inconnu, nom mal formé, manifeste refusé par le schéma, tier inconnu	Lire le message : il nomme le champ ou la règle en cause. Les champs inconnus sont refusés.
401	unauthorized	Jeton absent, expiré, signature invalide, JWT sans exp, ou session terminée par une déconnexion	Reprendre une identité (sng sso login) ou rouvrir une session (POST /v1/iam/session). La CLI le fait seule.
403	forbidden	La session n'a pas l'action IAM exigée par la route	Vérifier les policies attachées (catalogue des actions)
403	tenant session required	La route exige une session de tenant et a reçu un jeton d'identité	Appeler POST /v1/iam/session d'abord
403	identity token required	La route exige un jeton d'identité et a reçu une session	Utiliser le jeton d'identité (/v1/iam/me, /v1/templates, /v1/tenants)
403	forbidden: platform organization required	Création de tenant depuis une identité hors de l'organisation StackNGO	Se connecter avec un compte StackNGO
404	not found	Ressource inexistante dans ce tenant	Vérifier le nom et le tenant courant
409	conflict	Nom déjà pris, hôte déjà utilisé, ressource en cours de suppression	Choisir un autre nom ou attendre
409	policies_pending	Tenant tout juste créé, ses policies ne sont pas encore appliquées	Réessayer après Retry-After secondes (10 s). La CLI attend jusqu'à six minutes.
409	tier too small: …	Le tier du tenant ne permet pas la ressource demandée	Réduire la demande ou changer de tier
415	Content-Type must be application/json	Corps envoyé avec un autre type	Ajouter Content-Type: application/json
429	rate limit exceeded	Plus de 300 requêtes par minute depuis votre adresse IP	Attendre Retry-After, lisser les appels (Limites)
501	feature not available	Fonctionnalité désactivée sur cet environnement (CDN, registraire)	Rien à faire côté client
502	upstream unauthorized	Le service de secrets a refusé l'appel de l'API	Réessayer ; si ça persiste, contacter le support
503	authorization service unavailable	Le service d'autorisation ou le service de quota ne répond pas. Aucun accès n'est accordé dans ce cas.	Réessayer avec un délai croissant
500	internal server error	Erreur inattendue	Réessayer ; signaler avec l'heure et la route

Principes

• Refus par défaut. Un doute sur une permission, une indisponibilité du service d'autorisation : la réponse est 403 ou 503, jamais un accès. Un client ne doit pas interpréter un 503 comme « probablement autorisé ».
• Pas de divulgation. Un 404 et un 403 peuvent se ressembler volontairement : l'API ne confirme pas l'existence d'une ressource à qui n'a pas le droit de la lire.
• Messages stables. Les messages listés ci-dessus peuvent servir de clés dans un client ; le texte libre qui les suit parfois (après : ) peut changer.

Les erreurs dans la CLI

La CLI affiche le message de l'erreur, parfois complété d'une consigne (un 401 devient session expired: run sng tenant use NAME, un 403 rappelle sng tenant policy list), et sort avec le code 1. Avec -v, elle ajoute la méthode et l'URL entre parenthèses. Voir Erreurs CLI pour les messages propres à la CLI (non connecté, tenant manquant, fichier introuvable).

Erreurs d'application d'un manifeste

Un manifeste refusé par POST /v1/apply répond 400 avec un message qui nomme l'objet et la règle :

{"error": "invalid manifest App/web: spec.services.db: volumes require replicas <= 1 and strategy recreate"}

Un manifeste accepté peut encore échouer plus tard, à la convergence : cela ne se voit pas dans la réponse HTTP mais dans le status de la ressource. Voir Conditions et raisons.