Fehlerbehandlung

Das SDK transformiert alle API-Fehler in typisierte Fehlerklassen mit umfangreichen Metadaten. Alle Fehler erweitern SonarSDKError.

Fehlerklassen-Hierarchie

SonarSDKError (Basis)
  ├── AuthenticationError    (401/403)
  ├── RateLimitError         (429)
  ├── DocumentNotFoundError  (404)
  └── ValidationError        (400)

Basisfehler — SonarSDKError

Alle SDK-Fehler erweitern diese Basisklasse.

Eigenschaft	Typ	Beschreibung
message	string	Menschenlesbare Fehlermeldung
code	ErrorCode | string	Maschinenlesbarer Fehlercode
status	number?	HTTP-Statuscode
requestId	string?	Eindeutige Anfrage-ID zum Debugging
details	Record<string, unknown>?	Zusätzlicher Fehlerkontext
errors	FieldError[]?	Array von Feld-Validierungsfehlern
timestamp	string	ISO 8601 Zeitstempel der Fehlererstellung

Methoden: toJSON() — Serialisiert den Fehler in ein einfaches Objekt.

try {
  await sdk.documents.get('invalid_id');
} catch (err) {
  if (err instanceof SonarSDKError) {
    console.log(err.code);       // "DOCUMENT_NOT_FOUND"
    console.log(err.status);     // 404
    console.log(err.requestId);  // "req_abc123"
    console.log(err.timestamp);  // "2025-06-01T12:00:00.000Z"
    console.log(err.toJSON());   // serialisiertes Fehlerobjekt
  }
}

---

AuthenticationError

Wird bei Authentifizierungs- und Autorisierungsfehlern ausgelöst (HTTP 401/403).

Häufige Ursachen:

• Fehlender API-Schlüssel
• API-Schlüssel beginnt nicht mit sk_
• Abgelaufener oder widerrufener API-Schlüssel
• Unzureichende Berechtigungen für die angeforderte Operation

import { AuthenticationError } from '@sonar/sdk';

try {
  const sdk = new SonarSDK({ apiKey: 'bad_key', instanceName: 'demo' });
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.log(err.message); // "API-Schlüssel muss mit \"sk_\" beginnen"
    console.log(err.code);    // "INVALID_API_KEY"
  }
}

---

RateLimitError

Wird ausgelöst, wenn das API-Ratenlimit überschritten wird (HTTP 429).

Eigenschaft	Typ	Beschreibung
code	string	Immer 'RATE_LIMIT_EXCEEDED'
retryAfter	number?	Sekunden bis zum erneuten Versuch

import { RateLimitError } from '@sonar/sdk';

try {
  await sdk.documents.list();
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`Ratenlimit erreicht. Erneuter Versuch nach ${err.retryAfter} Sekunden`);
    await new Promise(r => setTimeout(r, (err.retryAfter || 60) * 1000));
  }
}

---

DocumentNotFoundError

Wird ausgelöst, wenn ein angefordertes Dokument nicht existiert (HTTP 404).

Eigenschaft	Typ	Beschreibung
code	string	Immer 'DOCUMENT_NOT_FOUND'
status	number	Immer 404
documentId	string	Die nicht gefundene ID

import { DocumentNotFoundError } from '@sonar/sdk';

try {
  await sdk.documents.get('doc_nonexistent');
} catch (err) {
  if (err instanceof DocumentNotFoundError) {
    console.log(`Dokument ${err.documentId} nicht gefunden`);
  }
}

---

ValidationError

Wird bei client- oder serverseitigen Validierungsfehlern ausgelöst (HTTP 400).

Eigenschaft	Typ	Beschreibung
code	string	Immer 'INVALID_REQUEST'
status	number	Immer 400
errors	FieldError[]?	Array von Feldfehlern

Jeder FieldError: { field: string; code: string; message: string }

import { ValidationError } from '@sonar/sdk';

try {
  await sdk.documents.export({ documentIds: [] });
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.message);  // "Mindestens eine Dokument-ID ist erforderlich"
    if (err.errors) {
      err.errors.forEach(e => {
        console.log(`  ${e.field}: ${e.message} (${e.code})`);
      });
    }
  }
}

---

Umfassendes Fehlerbehandlungsmuster

import {
  SonarSDK,
  SonarSDKError,
  AuthenticationError,
  RateLimitError,
  DocumentNotFoundError,
  ValidationError,
} from '@sonar/sdk';

async function safeDocumentFetch(sdk: SonarSDK, id: string) {
  try {
    return await sdk.documents.get(id);
  } catch (err) {
    if (err instanceof DocumentNotFoundError) {
      console.error(`Dokument ${err.documentId} existiert nicht`);
      return null;
    }
    if (err instanceof AuthenticationError) {
      console.error(`Authentifizierung fehlgeschlagen: ${err.code} — ${err.message}`);
      throw err;
    }
    if (err instanceof RateLimitError) {
      const wait = err.retryAfter || 60;
      console.warn(`Ratenlimit erreicht, erneuter Versuch in ${wait}s...`);
      await new Promise(r => setTimeout(r, wait * 1000));
      return safeDocumentFetch(sdk, id);
    }
    if (err instanceof ValidationError) {
      console.error('Validierungsfehler:', err.errors);
      throw err;
    }
    if (err instanceof SonarSDKError) {
      console.error(`SDK-Fehler [${err.code}]: ${err.message}`);
      console.error(`Anfrage-ID: ${err.requestId}`);
      throw err;
    }
    throw err;
  }
}

---

Fehlercode-Referenz

Fehlercode	HTTP-Status	Fehlerklasse	Beschreibung
MISSING_API_KEY	401	AuthenticationError	Kein API-Schlüssel angegeben
INVALID_API_KEY	401	AuthenticationError	API-Schlüssel ist fehlerhaft oder ungültig
EXPIRED_API_KEY	401	AuthenticationError	API-Schlüssel ist abgelaufen
REVOKED_API_KEY	401	AuthenticationError	API-Schlüssel wurde widerrufen
INSUFFICIENT_SCOPE	403	AuthenticationError	API-Schlüssel hat nicht die erforderlichen Berechtigungen
IP_NOT_ALLOWED	403	AuthenticationError	Anfrage-IP ist nicht in der Erlaubnisliste
RATE_LIMIT_EXCEEDED	429	RateLimitError	Zu viele Anfragen
DOCUMENT_NOT_FOUND	404	DocumentNotFoundError	Angefordertes Dokument existiert nicht
RESOURCE_NOT_FOUND	404	SonarSDKError	Allgemeine Ressource nicht gefunden
INVALID_REQUEST	400	ValidationError	Anfragevalidierung fehlgeschlagen
INVALID_PARAMETER	400	ValidationError	Bestimmter Parameter ist ungültig
EXPORT_LIMIT_EXCEEDED	400	ValidationError	Zu viele Dokumente für den Export angefordert
EXPORT_SIZE_EXCEEDED	400	ValidationError	Gesamte Exportgröße überschreitet Limit
EXPORT_NO_FILES	400	ValidationError	Keine Dateien für die angegebenen Dokument-IDs gefunden
INTERNAL_ERROR	500	SonarSDKError	Unerwarteter Serverfehler