---

Fehlerantwortformat

Blues GraphQL API gibt Fehler in einem standardisierten Format gemäß der GraphQL-Spezifikation zurück. Wenn ein Fehler auftritt, enthält die Antwort ein errors Array mit detaillierten Informationen darüber, was schiefgelaufen ist.

Beispiel für eine Fehlerantwort

{
  "errors": [
    {
      "message": "Todo was not found.",
      "extensions": {
        "code": "TODO_NOT_FOUND"
      }
    }
  ]
}

Fehlerstruktur

Jedes Fehlerobjekt enthält:

• message: Eine für Menschen lesbare Beschreibung des Fehlers
• extensions.code: Ein maschinenlesbarer Fehlercode für die programmgesteuerte Verarbeitung

Produktionsfehler-Sicherheit

Blue implementiert ein Sicherheitssystem für die Fehlerexposition:

• Sichere Fehler: Zeigen Sie tatsächliche Fehlercodes und -nachrichten an die Clients an
• Nicht-sichere Fehler: Geben Sie generische INTERNAL_SERVER_ERROR zurück, um sensible Details zu verbergen
• Ressource nicht gefunden: Alle *_NOT_FOUND Fehler gelten als sicher und werden immer angezeigt

Fehlerkategorien

Blue definiert 108 benutzerdefinierte Fehlercodes, die in die folgenden Kategorien organisiert sind:

Authentifizierungs- und Autorisierungsfehler

Fehlercode	Nachricht	Beschreibung
UNAUTHENTICATED	"Authentifizierung erforderlich."	Anfrage erfordert Authentifizierung, aber keine bereitgestellt
FORBIDDEN	"Sie sind nicht autorisiert."	Authentifiziert, aber es fehlen die erforderlichen Berechtigungen

Ressource nicht gefunden Fehler (insgesamt 52)

Kernressourcen

Fehlercode	Nachricht	Beschreibung
TODO_NOT_FOUND	"Todo wurde nicht gefunden."	Datensatz/Todo existiert nicht oder Benutzer hat keinen Zugriff
TODO_LIST_NOT_FOUND	"Todo-Liste wurde nicht gefunden."	Liste existiert nicht oder Benutzer hat keinen Zugriff
PROJECT_NOT_FOUND	"Projekt wurde nicht gefunden."	Projekt existiert nicht oder Benutzer hat keinen Zugriff
COMPANY_NOT_FOUND	"Unternehmen wurde nicht gefunden."	Unternehmen existiert nicht oder Benutzer hat keinen Zugriff
USER_NOT_FOUND	"Benutzer wurde nicht gefunden."	Benutzer existiert nicht im System

Benutzerdefinierte Felder & Formulare

Fehlercode	Nachricht	Beschreibung
CUSTOM_FIELD_NOT_FOUND	"Benutzerdefiniertes Feld wurde nicht gefunden."	Benutzerdefiniertes Feld existiert nicht
CUSTOM_FIELD_OPTION_NOT_FOUND	"Benutzerdefinierte Feldoption wurde nicht gefunden."	Auswahlfeldoption existiert nicht
FORM_NOT_FOUND	"Formular wurde nicht gefunden."	Formularvorlage existiert nicht
FORM_FIELD_NOT_FOUND	"Formularfeld wurde nicht gefunden."	Formularfeld existiert nicht

Projektkomponenten

Fehlercode	Nachricht	Beschreibung
TAG_NOT_FOUND	"Tag wurde nicht gefunden."	Tag existiert im Projekt nicht
AUTOMATION_NOT_FOUND	"Automatisierung wurde nicht gefunden."	Automatisierungsregel existiert nicht
CHART_NOT_FOUND	"Diagramm wurde nicht gefunden."	Dashboard-Diagramm existiert nicht
WEBHOOK_NOT_FOUND	"Webhook wurde nicht gefunden."	Webhook-Konfiguration existiert nicht
TEMPLATE_NOT_FOUND	"Vorlage wurde nicht gefunden."	Projektvorlage existiert nicht

Kommentare & Aktivitäten

Fehlercode	Nachricht	Beschreibung
COMMENT_NOT_FOUND	"Kommentar wurde nicht gefunden."	Kommentar existiert nicht
ACTIVITY_NOT_FOUND	"Aktivität wurde nicht gefunden."	Aktivitätseintrag existiert nicht
REACTION_NOT_FOUND	"Reaktion wurde nicht gefunden."	Kommentarreaktion existiert nicht

Andere Ressourcen

Fehlercode	Nachricht	Beschreibung
FILE_NOT_FOUND	"Datei wurde nicht gefunden."	Dateianhang existiert nicht
SUBSCRIPTION_NOT_FOUND	"Abonnement nicht gefunden."	Abonnement für die Abrechnung existiert nicht
INVOICE_NOT_FOUND	"Rechnung nicht gefunden."	Rechnungsdatensatz existiert nicht
CHECKLIST_NOT_FOUND	"Checkliste wurde nicht gefunden."	Checkliste existiert nicht
CHECKLIST_ITEM_NOT_FOUND	"Checklistenpunkt wurde nicht gefunden."	Checklistenpunkt existiert nicht
PROJECT_ROLE_NOT_FOUND	"Projektrolle wurde nicht gefunden."	Benutzerdefinierte Projektrolle existiert nicht
PROJECT_ACCESS_NOT_FOUND	"Projektzugriff wurde nicht gefunden."	Benutzerprojektzugriff existiert nicht
NOTIFICATION_NOT_FOUND	"Benachrichtigung wurde nicht gefunden."	Benachrichtigung existiert nicht
DASHBOARD_NOT_FOUND	"Dashboard wurde nicht gefunden."	Dashboard existiert nicht
KEY_NOT_FOUND	"Schlüssel wurde nicht gefunden."	Einstellungs-Schlüssel existiert nicht

Validierungsfehler

Fehlercode	Nachricht	Beschreibung
BAD_USER_INPUT	"Ungültige Eingabe."	Allgemeiner Validierungsfehler der Eingabe
VALIDATION_ERROR	"Ungültige Parameter"	Anfrageparameter haben die Validierung nicht bestanden
BAD_EMAIL	"Sie müssen eine gültige E-Mail-Adresse eingeben."	Ungültiges E-Mail-Format
INVALID_IDS	"Ungültige IDs."	Eine oder mehrere IDs in der Anfrage sind ungültig
PHONE_INVALID	"Telefonnummer ist ungültig."	Ungültiges Telefonnummernformat
URL_INVALID	"URL ist ungültig."	Ungültiges URL-Format
INVALID_RECURRING_DUE_DATE	"Ungültiges Fälligkeitsdatum für wiederkehrende Aufgaben"	Validierung des Datums für wiederkehrende Aufgaben fehlgeschlagen
INVALID_COLOR	"Ungültige Farbe"	Farbwert entspricht nicht dem erwarteten Format

Geschäftslogikfehler

Limits & Quoten

Fehlercode	Nachricht	Beschreibung
COMPANY_LIMIT	"Sie haben das Unternehmenslimit für Ihr Konto erreicht."	Maximale Anzahl an Unternehmen erreicht
PROJECT_LIMIT	"Sie haben das Projektlimit für Ihr Unternehmen erreicht."	Maximale Anzahl an Projekten erreicht
USER_LIMIT	"Sie haben das Benutzerlimit für Ihr Unternehmen erreicht."	Maximale Anzahl an Benutzern erreicht
PROJECT_TEMPLATE_LIMIT	"Sie haben das Vorlagenlimit für Ihr Unternehmen erreicht."	Maximale Anzahl an Vorlagen erreicht
CUSTOM_FIELD_LIMIT	"Limit für benutzerdefinierte Felder erreicht."	Maximale Anzahl an benutzerdefinierten Feldern erreicht
TODO_LIST_LIMIT	"Sie haben das Listenlimit für Ihr Projekt erreicht."	Maximale Anzahl an Listen pro Projekt
TOO_MANY_TODOS	"Zu viele Todos."	Datensatzlimit überschritten
TOO_MANY_OPTIONS	"Zu viele Optionen."	Limit für Auswahlfeldoptionen überschritten
MAX_FILE_SIZE	"Maximale Dateigröße beträgt 4,8 GB"	Limit für die Dateigröße beim Hochladen überschritten

Ressourcen-Konflikte

Fehlercode	Nachricht	Beschreibung
TAG_ALREADY_EXISTS	"Tag existiert bereits."	Tag mit demselben Namen existiert im Projekt
COMPANY_SLUG_ALREADY_EXISTS	"Unternehmen existiert bereits."	Unternehmens-Slug/URL ist vergeben
USER_ALREADY_EXISTS	"Benutzer existiert bereits."	Benutzer-E-Mail ist bereits registriert
ALREADY_INVITED	"Der Benutzer ist bereits eingeladen."	Benutzer hat bereits eine ausstehende Einladung
USER_ALREADY_IN_PROJECT	"Benutzer ist bereits in diesem Projekt."	Benutzer hat bereits Zugriff auf das Projekt
FILE_TYPE_NOT_ALLOWED	"Dateityp nicht erlaubt."	Hochgeladener Dateityp ist eingeschränkt

Berechtigungs- und Zugriffsfehler

Fehlercode	Nachricht	Beschreibung
UNABLE_TO_DELETE_ONLY_ADMIN	"Kann den einzigen Administrator im Unternehmen nicht löschen."	Letzten Administrator kann nicht entfernt werden
UNABLE_TO_UPDATE_OWNER	"Kann den EIGENTÜMER nicht aktualisieren."	Berechtigungen des Eigentümers können nicht geändert werden
TODO_LIST_IS_HIDDEN	"Todo-Liste ist verborgen."	Liste ist für die Rolle des Benutzers verborgen
COMPANY_NOT_ACTIVE	"Unternehmen ist nicht aktiv."	Unternehmensabonnement ist inaktiv
PROJECT_NOT_ACTIVE	"Projekt ist nicht aktiv."	Projekt ist archiviert/inaktiv

Datenintegritätsfehler

Fehlercode	Nachricht	Beschreibung
UNABLE_TO_DELETE_LIST_WITH_TODOS	"Kann Liste mit Todos nicht löschen."	Liste muss leer sein, um gelöscht zu werden
UNABLE_TO_DELTE_FILE	"Kann Datei nicht löschen."	Dateilöschung fehlgeschlagen (Tippfehler im Code)
UNABLE_TO_MOVE_TODO	"Kann Todo nicht verschieben."	Datensatz kann nicht zwischen Listen verschoben werden
DEPENDENCY_HAS_DEPENDENCY	"Abhängigkeit hat Abhängigkeit"	Zirkuläre Abhängigkeit erkannt
TODO_DEPENDS_ON_ITSELF	"Todo hängt von sich selbst ab"	Selbstreferenzielle Abhängigkeit

Stripe/Zahlungsfehler

Fehlercode	Nachricht	Beschreibung
STRIPE_CREATING_CUSTOMER	"Fehler beim Erstellen des Kunden in Stripe."	Erstellung des Stripe-Kunden fehlgeschlagen
STRIPE_ALREADY_SUBSCRIBED	"Bereits abonniert."	Aktives Abonnement existiert
STRIPE_MISSING_PAYMENT_METHOD	"Zahlungsmethode fehlt."	Keine Zahlungsmethode hinterlegt
STRIPE_CREATING_SUBSCRIPTION	"Fehler beim Erstellen des Abonnements in Stripe."	Erstellung des Abonnements fehlgeschlagen
STRIPE_UPDATING_SUBSCRIPTION	"Fehler beim Aktualisieren des Abonnements in Stripe."	Aktualisierung des Abonnements fehlgeschlagen
STRIPE_CHECKOUT_SESSION	"Fehler beim Erstellen der Checkout-Sitzung in Stripe."	Erstellung der Checkout-Sitzung fehlgeschlagen
STRIPE_CUSTOMER_PORTAL	"Fehler beim Erstellen des Kundenportals in Stripe."	Erstellung der Portalsitzung fehlgeschlagen
STRIPE_TAX_ID	"Kann Steuer-ID nicht speichern"	Validierung/Speicherung der Steuer-ID fehlgeschlagen
PAYMENT_REQUIRED	"Zahlung erforderlich."	Funktion erfordert aktives Abonnement
NO_PAYMENT_REQUIRED	"Keine Zahlung erforderlich."	Zahlung nicht notwendig für die Operation

Authentifizierungs- und Sitzungsfehler

Fehlercode	Nachricht	Beschreibung
INVALID_CREDENTIALS	"Ungültige Anmeldeinformationen."	Benutzername/Passwort falsch
EXPIRED_RESET_TOKEN	"Zurücksetz-Token ist abgelaufen."	Passwort-Zurücksetz-Token abgelaufen
OAUTH_FAILED	"OAuth-Prozess fehlgeschlagen."	OAuth-Authentifizierung fehlgeschlagen
SAML_NOT_ENABLED	"SSO (SAML) ist nicht aktiviert."	SAML SSO nicht konfiguriert
SSO_AUTO_PROVISION_DISABLED	"Automatische Bereitstellung ist deaktiviert."	SSO-Benutzer können nicht automatisch erstellt werden

Ratenbegrenzung

Die Ratenbegrenzung wird vom graphql-rate-limit Paket mit unterschiedlichen Konfigurationen behandelt:

Limittyp	Fenster	Max. Anfragen	Angewendet auf
Standard	60s	500	Most queries/mutations
Sensitive	300s	10	Password reset, auth operations
Expensive	60s	20	Complex queries, bulk operations
Search	60s	60	Search operations
File Upload	60s	100	File upload operations

Wenn die Ratenbegrenzung erreicht ist, erhalten Sie einen standardmäßigen GraphQL-Fehler mit einer Nachricht, die angibt, dass das Limit überschritten wurde.

System- und interne Fehler

Fehlercode	Nachricht	Beschreibung
INTERNAL_SERVER_ERROR	"Interner Serverfehler."	Allgemeiner Fehler für nicht sichere Fehler in der Produktion
UNKNOWN_ERROR	"Unbekannter Fehler."	Unerwarteter Fehler aufgetreten
RESOLVER_NOT_FOUND	"Resolver nicht gefunden"	GraphQL-Resolver fehlt
FIELD_NOT_IN_SCHEMA	"Feld nicht im Schema"	Angefordertes Feld existiert nicht

Beste Praktiken für die Fehlerbehandlung

Clientseitige Behandlung

try {
  const result = await client.mutate({
    mutation: CREATE_TODO,
    variables: { input }
  });
} catch (error) {
  if (error.graphQLErrors?.length > 0) {
    const errorCode = error.graphQLErrors[0].extensions?.code;
    
    switch (errorCode) {
      case 'UNAUTHENTICATED':
        // Redirect to login
        break;
      case 'TODO_NOT_FOUND':
        // Show "Record not found" message
        break;
      case 'VALIDATION_ERROR':
        // Display validation errors
        break;
      default:
        // Show generic error message
    }
  }
}

Häufige Fehlerszenarien

1. Authentifizierung erforderlich: UNAUTHENTICATED - Benutzer muss sich anmelden
2. Zugriff verweigert: FORBIDDEN - Benutzer hat nicht die erforderliche Rolle/Berechtigung
3. Ressource nicht gefunden: *_NOT_FOUND - Ressource existiert nicht oder Benutzer kann nicht darauf zugreifen
4. Validierung fehlgeschlagen: VALIDATION_ERROR, BAD_USER_INPUT - Überprüfen Sie die Eingabeparameter
5. Ratenbegrenzung: Überprüfen Sie die Ratenbegrenzungs-Header und implementieren Sie ein Backoff
6. Zahlung erforderlich: PAYMENT_REQUIRED - Funktion erfordert ein Abonnement

Verwandte Dokumentation

• Authentifizierung - So authentifizieren Sie API-Anfragen
• Anfragen stellen - Anfrageformat und Header
• Ratenlimits - Detaillierte Informationen zur Ratenbegrenzung