Fehlerbehandlung

Fehlerformat

Die meisten API-Fehler geben ein JSON-Objekt mit einer einzelnen error-Zeichenfolge zurück:

{ "error": "Monitor not found" }

Einige Fehler umfassen zusätzliche Felder:

Rate-Limit-Fehler (429) enthalten ein retry_after_seconds-Feld:

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

OAuth-Token-Fehler folgen RFC 6749 und enthalten ein error_description:

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

HTTP-Statuscodes

Status	Bedeutung
400	Fehlerhafte Anfrage – fehlende oder ungültige Felder
401	Nicht authentifiziert – fehlendes, ungültiges oder abgelaufenes Token
403	Verboten – gültiges Token, aber unzureichende Berechtigungen oder Planlimit erreicht
404	Ressource nicht gefunden
429	Rate-Limit erreicht – kurz warten und erneut versuchen
500	Interner Serverfehler – vorübergehend, mit Backoff erneut versuchen
503	Dienst nicht verfügbar – Upstream-Abhängigkeit (z. B. OAuth-Anbieter) ist ausgefallen

Häufige Fehlermeldungen

Nachricht	Status	Was ist passiert
"Authorization header missing or invalid"	401	Kein Authorization: Bearer <token>-Header
"Invalid or expired token"	401	Token ist abgelaufen oder wurde manipuliert – erneut authentifizieren
"Invalid API key"	401	Der zum Generieren dieses Tokens verwendete API-Schlüssel wurde widerrufen
"Monitor not found"	404	In Ihrem Team ist kein Monitor mit dieser ID vorhanden
"Your plan allows a maximum of N monitors"	403	Aktualisieren Sie Ihren Plan, um mehr Monitore zu erstellen
"Too many requests"	429	Sie haben das Ratenlimit überschritten – siehe Feld retry_after_seconds
"Internal server error"	500	Vorübergehender Serverfehler – erneut versuchen mit exponentiellem Backoff

Umgang mit Fehlern im 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)
  }
}

5xx Fehler

Serverfehler sind vorübergehend. Wiederholen Sie den Versuch mit exponentiellem Backoff – die meisten werden innerhalb von Sekunden gelöst. Wenn ein 500 oder 503 länger als ein paar Minuten bestehen bleibt, überprüfen Sie unsere Statusseite oder senden Sie eine E-Mail an support@diffhook.com.