Fehlercodes

Wenn eine Anfrage fehlschlägt, gibt die SilentChat API eine JSON-Fehlerantwort mit einer einheitlichen Struktur zurück. Diese Seite dokumentiert das Antwortformat, alle Fehlercodes und die verwendeten HTTP-Statuscodes.

Fehlerantwort-Format

Jede Fehlerantwort hat folgende Struktur:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'email' field must be a valid email address.",
    "status": 400
  }
}

Field	Type	Description
`error.code`	`string`	Ein maschinenlesbarer Fehlercode im Format SCREAMING_SNAKE_CASE. Verwenden Sie diesen für die programmatische Fehlerbehandlung.
`error.message`	`string`	Eine für Menschen lesbare Nachricht, die beschreibt, was schiefgelaufen ist. Kann sicher dem Endbenutzer angezeigt werden.
`error.status`	`number`	Ein optionales Objekt mit zusätzlichem Kontext, z. B. Validierungsfehler auf Feldebene.

Fehlercodes

Code	HTTP Status	Description
`AUTH_MISSING_TOKEN`	401	Es wurden keine gültigen Zugangsdaten angegeben, oder das Access-Token ist abgelaufen.
`AUTH_INVALID_TOKEN`	401	Das angegebene Token ist fehlerhaft oder hat eine ungültige Signatur.
`AUTH_TOKEN_REVOKED`	401	Das JWT-Access-Token ist abgelaufen. Erneuern Sie es mit Ihrem Refresh-Token.
`AUTH_INVALID_CREDENTIALS`	401	Es wurden keine gültigen Zugangsdaten angegeben, oder das Access-Token ist abgelaufen.
`AUTH_EMAIL_NOT_VERIFIED`	403	Der authentifizierte Benutzer hat keine Berechtigung, diese Aktion auszuführen.
`FORBIDDEN`	403	Der authentifizierte Benutzer hat keine Berechtigung, diese Aktion auszuführen.
`TENANT_REQUIRED`	400	Ein oder mehrere Anfragefelder haben die Validierung nicht bestanden. Siehe details für feldspezifische Fehler.
`TENANT_NOT_FOUND`	404	Die angeforderte Ressource existiert nicht oder ist nicht zugänglich.
`VALIDATION_ERROR`	400	Ein oder mehrere Anfragefelder haben die Validierung nicht bestanden. Siehe details für feldspezifische Fehler.
`NOT_FOUND`	404	Die angeforderte Ressource existiert nicht oder ist nicht zugänglich.
`CONFLICT`	409	Die Anfrage steht im Widerspruch zum aktuellen Zustand der Ressource (z. B. doppelte E-Mail-Adresse).
`RATE_LIMITED`	429	Zu viele Anfragen. Verlangsamen Sie die Anfragen und wiederholen Sie sie nach der im Retry-After-Header angegebenen Dauer.
`WIDGET_KEY_INVALID`	401	Die Webhook-Nutzlast konnte nicht verifiziert werden. Überprüfen Sie Ihr Signing-Secret.
`WIDGET_DOMAIN_NOT_ALLOWED`	403	Der authentifizierte Benutzer hat keine Berechtigung, diese Aktion auszuführen.
`FILE_TOO_LARGE`	400	Ein oder mehrere Anfragefelder haben die Validierung nicht bestanden. Siehe details für feldspezifische Fehler.
`PLAN_LIMIT_EXCEEDED`	403	Ihr aktueller Plan lässt diese Aktion nicht zu. Führen Sie ein Upgrade durch, um diese Funktion freizuschalten.
`INTERNAL_ERROR`	500	Ein unerwarteter Serverfehler ist aufgetreten. Wenn das Problem anhält, wenden Sie sich an den Support.

HTTP-Statuscodes

Die API verwendet standardmäßige HTTP-Statuscodes. Hier ist eine Übersicht der Codes, die auftreten können:

Status	Meaning	When
`200`	OK	Die Anfrage war erfolgreich.
`201`	Created	Eine neue Ressource wurde erfolgreich erstellt.
`204`	No Content	Die Anfrage war erfolgreich, ohne Antwortinhalt (z. B. nach einem DELETE).
`400`	Bad Request	Die Anfrage war fehlerhaft oder hat die Validierung nicht bestanden.
`401`	Unauthorized	Eine Authentifizierung ist erforderlich, oder die Zugangsdaten sind ungültig.
`403`	Forbidden	Der Aufrufer ist authentifiziert, aber nicht berechtigt, die Aktion auszuführen.
`404`	Not Found	Die Ressource wurde nicht gefunden.
`409`	Conflict	Die Anfrage steht im Widerspruch zum aktuellen Ressourcenstatus.
`429`	Too Many Requests	Der Aufrufer hat das Rate-Limit überschritten.
`500`	Internal Server Error	Ein unerwarteter serverseitiger Fehler ist aufgetreten.

Fehler im Code behandeln

Prüfen Sie immer das Feld code statt der Fehlermeldung als Text — die Meldung kann sich zwischen Versionen ändern, Fehlercodes bleiben jedoch stabil.

const response = await fetch('https://api.silentchat.de/api/v1/conversations', {
  headers: {
    'Authorization': 'Bearer ' + accessToken,
    'Content-Type': 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();

  switch (error.code) {
    case 'AUTH_INVALID_TOKEN':
      // Token expired - refresh and retry
      break;
    case 'RATE_LIMITED':
      // Wait and retry
      const retryAfter = response.headers.get('Retry-After');
      break;
    case 'VALIDATION_ERROR':
      // Fix request parameters
      console.error('Validation:', error.message);
      break;
    default:
      console.error(`API error [${error.code}]: ${error.message}`);
  }
}