Fehlerbehandlung

{
  "error": "Kurze Fehlerbeschreibung",
  "details": "Optional: Detaillierte Informationen",
  "field": "Optional: Betroffenes Feld bei Validierungsfehlern"
}

{
  "error": "Validierungsfehler",
  "details": [
    {
      "field": "email",
      "message": "Ungültige E-Mail-Adresse"
    },
    {
      "field": "organization",
      "message": "Organisation ist erforderlich"
    }
  ]
}

{
  "error": "Zu viele Anfragen. Bitte versuchen Sie es später erneut.",
  "retryAfter": 3600
}

{
  "error": "Validierungsfehler",
  "details": [
    {
      "field": "vatId",
      "message": "USt-IdNr. muss mit Ländercode beginnen (z.B. DE123456789)"
    }
  ]
}

interface RetryConfig {
  maxRetries: number;
  initialDelayMs: number;
  maxDelayMs: number;
  backoffMultiplier: number;
}

const DEFAULT_RETRY_CONFIG: RetryConfig = {
  maxRetries: 3,
  initialDelayMs: 1000,      // 1 Sekunde
  maxDelayMs: 30000,          // 30 Sekunden
  backoffMultiplier: 2        // Verdopplung
};

async function fetchWithRetry<T>(
  url: string,
  options: RequestInit,
  config: RetryConfig = DEFAULT_RETRY_CONFIG
): Promise<T> {
  let lastError: Error;
  let delay = config.initialDelayMs;

  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      // Erfolg
      if (response.ok) {
        return await response.json();
      }

      // Nicht wiederholbare Fehler
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        const error = await response.json();
        throw new Error(`Client error (${response.status}): ${error.error}`);
      }

      // Rate Limit - nutze Retry-After Header
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After');
        const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : delay;

        if (attempt < config.maxRetries) {
          console.log(`Rate limited. Retrying after ${waitTime}ms...`);
          await sleep(waitTime);
          continue;
        }
      }

      // Server-Fehler (5xx) - wiederholbar
      if (response.status >= 500) {
        throw new Error(`Server error: ${response.status}`);
      }

    } catch (error) {
      lastError = error as Error;

      // Letzter Versuch - Fehler werfen
      if (attempt === config.maxRetries) {
        throw lastError;
      }

      // Exponentielles Backoff
      console.log(`Attempt ${attempt + 1} failed. Retrying in ${delay}ms...`);
      await sleep(delay);
      delay = Math.min(delay * config.backoffMultiplier, config.maxDelayMs);
    }
  }

  throw lastError!;
}

function sleep(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms));
}

// Batch erstellen mit automatischen Retries
try {
  const batch = await fetchWithRetry(
    'https://api.steuermappe-pro.de/v1/batches',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        batch_name: 'Steuer 2024',
        mandant: { /* ... */ },
        documents: [ /* ... */ ]
      })
    },
    {
      maxRetries: 3,
      initialDelayMs: 1000,
      maxDelayMs: 30000,
      backoffMultiplier: 2
    }
  );

  console.log('Batch erstellt:', batch.batch_id);

} catch (error) {
  console.error('Fehler nach allen Versuchen:', error);
  // Fehlerbehandlung für finale Fehler
}

function calculateBackoffWithJitter(
  baseDelay: number,
  attempt: number,
  maxDelay: number
): number {
  // Exponentielles Backoff
  const exponentialDelay = baseDelay * Math.pow(2, attempt);

  // Full Jitter: Zufälliger Wert zwischen 0 und exponentialDelay
  const delay = Math.random() * exponentialDelay;

  // Maximal-Grenze
  return Math.min(delay, maxDelay);
}

// Verwendung
const delay = calculateBackoffWithJitter(1000, attempt, 30000);
await sleep(delay);

class SteuerMappeClient {
  private accessToken: string | null = null;
  private tokenExpiresAt: number = 0;

  async getValidToken(): Promise<string> {
    const now = Date.now();

    // Token noch gültig? (mit 5 Min Puffer)
    if (this.accessToken && this.tokenExpiresAt > now + 5 * 60 * 1000) {
      return this.accessToken;
    }

    // Neuen Token anfordern
    const tokenResponse = await fetch(
      'https://api.steuermappe-pro.de/v1/oauth/token',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          grant_type: 'client_credentials',
          client_id: process.env.CLIENT_ID,
          client_secret: process.env.CLIENT_SECRET,
          scope: 'batches:write batches:read results:read'
        })
      }
    );

    if (!tokenResponse.ok) {
      throw new Error('Token request failed');
    }

    const data = await tokenResponse.json();
    this.accessToken = data.access_token;
    this.tokenExpiresAt = now + data.expires_in * 1000;

    return this.accessToken;
  }

  async makeAuthenticatedRequest(url: string, options: RequestInit) {
    const token = await this.getValidToken();

    const response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${token}`
      }
    });

    // Token abgelaufen während Request?
    if (response.status === 401) {
      // Token zurücksetzen und nochmal versuchen
      this.accessToken = null;
      this.tokenExpiresAt = 0;

      const newToken = await this.getValidToken();
      return fetch(url, {
        ...options,
        headers: {
          ...options.headers,
          'Authorization': `Bearer ${newToken}`
        }
      });
    }

    return response;
  }
}

// Custom Error-Klassen
class ApiError extends Error {
  constructor(
    message: string,
    public statusCode: number,
    public errorCode?: string,
    public details?: any
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

class RateLimitError extends ApiError {
  constructor(
    message: string,
    public retryAfter: number
  ) {
    super(message, 429, 'RATE_LIMIT_EXCEEDED');
    this.name = 'RateLimitError';
  }
}

class AuthenticationError extends ApiError {
  constructor(message: string, errorCode: string) {
    super(message, 401, errorCode);
    this.name = 'AuthenticationError';
  }
}

// Error-Parsing
async function parseApiError(response: Response): Promise<never> {
  const body = await response.json().catch(() => ({}));

  switch (response.status) {
    case 401:
      throw new AuthenticationError(
        body.error || 'Authentication failed',
        body.error_code || 'UNAUTHORIZED'
      );

    case 429:
      const retryAfter = response.headers.get('Retry-After');
      throw new RateLimitError(
        body.error || 'Rate limit exceeded',
        retryAfter ? parseInt(retryAfter) : 3600
      );

    case 400:
    case 422:
      throw new ApiError(
        body.error || 'Validation failed',
        response.status,
        'VALIDATION_ERROR',
        body.details
      );

    default:
      throw new ApiError(
        body.error || 'Unknown error',
        response.status
      );
  }
}

// Verwendung
try {
  const response = await fetch(/* ... */);

  if (!response.ok) {
    await parseApiError(response);
  }

  return await response.json();

} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
    // Spezifische Behandlung
  } else if (error instanceof AuthenticationError) {
    console.log('Authentication failed. Refreshing token...');
    // Token refresh
  } else if (error instanceof ApiError) {
    console.log(`API Error: ${error.message} (Status: ${error.statusCode})`);
  } else {
    console.error('Unexpected error:', error);
  }
}

class CircuitBreaker {
  private failureCount = 0;
  private lastFailureTime = 0;
  private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED';

  constructor(
    private threshold: number = 5,           // Fehler bis Circuit öffnet
    private timeout: number = 60000,         // Zeit bis Circuit wieder schließt (60s)
    private resetTimeout: number = 30000     // Zeit im HALF_OPEN Zustand
  ) {}

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === 'OPEN') {
      const now = Date.now();

      // Genug Zeit vergangen?
      if (now - this.lastFailureTime >= this.timeout) {
        console.log('Circuit breaker: HALF_OPEN');
        this.state = 'HALF_OPEN';
      } else {
        throw new Error(`Circuit breaker OPEN. Retry after ${
          Math.ceil((this.timeout - (now - this.lastFailureTime)) / 1000)
        }s`);
      }
    }

    try {
      const result = await fn();

      // Erfolg - Circuit schließen
      if (this.state === 'HALF_OPEN') {
        console.log('Circuit breaker: CLOSED');
        this.state = 'CLOSED';
        this.failureCount = 0;
      }

      return result;

    } catch (error) {
      this.failureCount++;
      this.lastFailureTime = Date.now();

      // Threshold erreicht?
      if (this.failureCount >= this.threshold) {
        console.log('Circuit breaker: OPEN');
        this.state = 'OPEN';
      }

      throw error;
    }
  }
}

// Verwendung
const breaker = new CircuitBreaker(5, 60000);

try {
  const result = await breaker.execute(() =>
    fetch('https://api.steuermappe-pro.de/v1/batches')
  );
} catch (error) {
  console.error('Request failed or circuit open:', error);
}

interface ErrorLogEntry {
  timestamp: string;
  method: string;
  url: string;
  statusCode: number;
  errorCode?: string;
  message: string;
  requestId?: string;
  duration: number;
}

class ApiLogger {
  async logRequest(
    method: string,
    url: string,
    startTime: number,
    response: Response,
    error?: Error
  ) {
    const entry: ErrorLogEntry = {
      timestamp: new Date().toISOString(),
      method,
      url,
      statusCode: response.status,
      message: error?.message || response.statusText,
      requestId: response.headers.get('X-Request-ID') || undefined,
      duration: Date.now() - startTime
    };

    // In Produktionsumgebung: an Logging-Service senden
    if (response.status >= 400) {
      console.error('API Error:', JSON.stringify(entry, null, 2));

      // Optional: An Error-Tracking-Service senden
      // await sendToSentry(entry);
    } else {
      console.log('API Request:', JSON.stringify(entry, null, 2));
    }
  }
}

// Verwendung
const logger = new ApiLogger();
const startTime = Date.now();

try {
  const response = await fetch(url, options);
  await logger.logRequest(method, url, startTime, response);

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }

  return await response.json();

} catch (error) {
  await logger.logRequest(method, url, startTime, response, error as Error);
  throw error;
}

// Test für Rate Limit Handling
describe('Rate Limit Error Handling', () => {
  it('should retry after rate limit with exponential backoff', async () => {
    // Mock erste Anfrage mit 429
    fetchMock.mockResponseOnce(
      JSON.stringify({ error: 'Rate limit exceeded', retryAfter: 2 }),
      {
        status: 429,
        headers: { 'Retry-After': '2' }
      }
    );

    // Mock zweite Anfrage erfolgreich
    fetchMock.mockResponseOnce(
      JSON.stringify({ batch_id: 'b_123' }),
      { status: 202 }
    );

    const result = await fetchWithRetry(/* ... */);

    expect(result.batch_id).toBe('b_123');
    expect(fetchMock).toHaveBeenCalledTimes(2);
  });

  it('should throw after max retries', async () => {
    // Mock alle Anfragen mit 500
    fetchMock.mockResponse(
      JSON.stringify({ error: 'Internal server error' }),
      { status: 500 }
    );

    await expect(fetchWithRetry(/* ... */, { maxRetries: 3 }))
      .rejects.toThrow('Server error: 500');

    expect(fetchMock).toHaveBeenCalledTimes(4); // Initial + 3 retries
  });
});

// Integration Test mit echten API-Aufrufen
describe('API Error Handling Integration', () => {
  it('should handle invalid token and refresh', async () => {
    const client = new SteuerMappeClient({
      clientId: 'test_client',
      clientSecret: 'test_secret'
    });

    // Erster Request mit abgelaufenem Token
    const response = await client.getBatch('b_123');

    // Client sollte automatisch Token refreshen
    expect(response.batch_id).toBe('b_123');
  });

  it('should respect rate limits', async () => {
    const requests = Array.from({ length: 15 }, (_, i) =>
      api.validatePartnerCode('ABC123')
    );

    const results = await Promise.allSettled(requests);

    const rateLimited = results.filter(r =>
      r.status === 'rejected' &&
      r.reason.statusCode === 429
    );

    // Erwarte dass einige Rate Limited wurden
    expect(rateLimited.length).toBeGreaterThan(0);
  });
});