Gestion des erreurs

Format d'erreur

La plupart des erreurs d'API renvoient un objet JSON avec une seule chaîne error. Cette référence couvre les codes HTTP, les messages de validation, les conseils de réessai et la remontée d'erreurs dans les handlers.

{ "error": "Monitor not found" }

Certaines erreurs incluent des champs supplémentaires :

Les erreurs de limite de débit (429) incluent un champ retry_after_seconds :

{
  "error": "Too many requests",
  "retry_after_seconds": 60
}

Les erreurs de jeton OAuth suivent RFC 6749 et incluent un error_description :

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Codes d'état HTTP

Statut	Signification
400	Mauvaise demande — champs manquants ou invalides
401	Non authentifié : jeton manquant, invalide ou expiré
403	Interdit : jeton valide mais autorisations insuffisantes ou limite du plan atteinte
404	Ressource introuvable
429	Limite de débit atteinte — réessayez
500	Erreur de serveur interne : transitoire, réessayez avec interruption
503	Service indisponible – la dépendance en amont (par exemple, le fournisseur OAuth) est en panne

Messages d'erreur courants

Messages	Statut	Que s'est-il passé
"Authorization header missing or invalid"	401	Pas d'en-tête Authorization: Bearer <token>
"Invalid or expired token"	401	Le jeton a expiré ou a été falsifié — réauthentifier
"Invalid API key"	401	La clé API utilisée pour générer ce jeton a été révoquée
"Monitor not found"	404	Aucun moniteur avec cet ID n'existe dans votre équipe
"Your plan allows a maximum of N monitors"	403	Mettez à niveau votre plan pour créer plus de moniteurs
"Too many requests"	429	Vous avez dépassé la limite de débit — voir le champ retry_after_seconds
"Internal server error"	500	Erreur de serveur transitoire : réessayez avec une interruption exponentielle

Gestion des erreurs dans le code

const res = await fetch('https://www.diffhook.com/api/monitors', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
})

if (!res.ok) {
  const body = await res.json()
  const message = body.error

  if (res.status === 429) {
    const retryAfter = body.retry_after_seconds ?? 60
    // wait and retry
  } else if (res.status === 401) {
    // re-authenticate with POST /api/oauth/token
  } else {
    console.error(message)
  }
}

Erreurs 5xx

Les erreurs du serveur sont transitoires. Réessayez avec un intervalle exponentiel : la plupart sont résolus en quelques secondes. Si un 500 ou 503 persiste pendant plus de quelques minutes, consultez notre page d'état ou envoyez un e-mail à support@diffhook.com.