Erreurs

Lorsqu'une requête ne peut pas aboutir, l'API Servor renvoie un code de statut HTTP standard et un corps JSON typé. Cette page montre la forme d'une réponse d'erreur et liste chaque code de statut que vous rencontrerez, avec sa cause et la façon d'y remédier.

Forme d'une erreur

Chaque erreur est un JSON avec un champ error lisible, un champ code stable et exploitable par une machine, et parfois un objet details apportant plus de contexte :

{
  "error": "Missing required scope: incidents:write",
  "code": "forbidden",
  "details": { "required": "incidents:write" }
}

Dans votre intégration, testez le code plutôt que le texte de error : le message peut être reformulé, mais le code reste stable.

Codes de statut

401 — Non authentifié

Le jeton est absent, mal formé, ou n'est plus valide (par exemple parce qu'il a été révoqué).

• Vérifiez que l'en-tête est exactement Authorization: Bearer sv_live_....
• Confirmez que le jeton n'a pas été révoqué ni remplacé.
• Vérifiez-le avec GET /v1/me — voir Authentification.

{ "error": "Invalid or missing token", "code": "unauthorized" }

403 — Interdit

Le jeton est valide mais ne porte pas le scope exigé par l'endpoint. C'est l'erreur la plus fréquente quand une intégration s'étend à un nouvel endpoint.

• Lisez details.required pour savoir quel scope manque.
• Créez un nouveau jeton avec les bons scopes — on ne peut pas ajouter de scopes à un jeton existant, donc générez un remplaçant et faites la rotation. Ouvrez les jetons API dans Servor.

{
  "error": "Missing required scope: monitors:read",
  "code": "forbidden",
  "details": { "required": "monitors:read" }
}

404 — Introuvable

L'id de la ressource n'existe pas, ou appartient à une autre équipe que celle de votre jeton. Un jeton ne voit que les données de sa propre équipe : un id valide provenant d'une autre équipe renvoie donc quand même 404.

• Revérifiez l'id et qu'il appartient bien à votre équipe.
• Confirmez que la ressource n'a pas été supprimée dans le tableau de bord.

{ "error": "Server not found", "code": "not_found" }

422 — Entité non traitable

La requête a atteint un endpoint valide, mais le corps a échoué à la validation — champ obligatoire manquant, mauvais type ou valeur invalide. Vous le verrez surtout sur les endpoints incidents:write.

• Lisez details pour les problèmes champ par champ et corrigez la charge utile.
• Vérifiez les champs obligatoires (par exemple, un incident exige un titre et un statut).

{
  "error": "Validation failed",
  "code": "validation_error",
  "details": { "title": "Required", "status": "Invalid value" }
}

429 — Trop de requêtes

Vous avez dépassé la limite de débit par jeton. La réponse inclut un en-tête retry-after indiquant combien de secondes attendre.

• Lisez retry-after et patientez exactement ce délai avant de réessayer.
• Voir limites de débit pour un modèle de réessai prêt à l'emploi.

{ "error": "Rate limit exceeded", "code": "rate_limited" }

Bien gérer les erreurs

• Testez le code, pas le message. Les codes sont stables ; la formulation peut changer.
• Traitez le 429 comme un contrôle de flux. Faites du back-off et réessayez au lieu d'échouer brutalement.
• Échouez bruyamment sur 401/403. Ils signalent un problème de jeton ou de scope à corriger — faites la rotation du jeton ou accordez le bon scope.
• Journalisez details sur un 422. Il indique exactement quel champ corriger.

Voir aussi