Fehlerbehandlung

Die CODEFLUSS API verwendet standardmäßige HTTP-Statuscodes und strukturierte JSON-Fehlerresponses für konsistente Fehlerbehandlung.

Fehler-Response Format

Alle Fehler folgen diesem einheitlichen Format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Menschenlesbare Fehlerbeschreibung",
    "details": {
      // Optionale zusätzliche Informationen
    }
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-01-23T12:00:00Z"
  }
}

HTTP-Statuscodes

Erfolgreiche Responses (2xx)

Code	Bedeutung	Beschreibung
`200`	OK	Anfrage erfolgreich
`201`	Created	Ressource erfolgreich erstellt
`204`	No Content	Erfolgreich, keine Daten zurück (z.B. DELETE)

Client-Fehler (4xx)

Code	Bedeutung	Beschreibung
`400`	Bad Request	Ungültige Anfrage oder Validierungsfehler
`401`	Unauthorized	Authentifizierung erforderlich oder fehlgeschlagen
`402`	Payment Required	Limit erreicht, Upgrade erforderlich
`403`	Forbidden	Keine Berechtigung für diese Ressource
`404`	Not Found	Ressource existiert nicht
`409`	Conflict	Ressourcenkonflikt (z.B. Duplikat)
`422`	Unprocessable Entity	Semantischer Fehler in den Daten
`429`	Too Many Requests	Rate Limit überschritten

Server-Fehler (5xx)

Code	Bedeutung	Beschreibung
`500`	Internal Server Error	Unerwarteter Serverfehler
`502`	Bad Gateway	Upstream-Service nicht erreichbar
`503`	Service Unavailable	Temporär nicht verfügbar

Fehlercodes

Validierungsfehler

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "issues": [
        {
          "field": "name",
          "code": "too_small",
          "message": "Name must be at least 3 characters"
        },
        {
          "field": "email",
          "code": "invalid_email",
          "message": "Invalid email format"
        }
      ]
    }
  }
}

Authentifizierungsfehler

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Berechtigungsfehler

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource",
    "details": {
      "required": "projects:write",
      "provided": ["projects:read"]
    }
  }
}

Ressource nicht gefunden

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Project not found",
    "details": {
      "resourceType": "project",
      "resourceId": "proj_abc123"
    }
  }
}

Limit erreicht (402 Payment Required)

{
  "success": false,
  "error": {
    "code": "LIMIT_REACHED",
    "message": "Project limit reached for your plan",
    "details": {
      "resourceType": "projects",
      "current": 5,
      "limit": 5,
      "plan": "starter",
      "upgradeUrl": "https://codefluss.com/pricing"
    }
  }
}

Rate Limit

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "details": {
      "retryAfter": 45,
      "limit": 60,
      "windowSeconds": 60
    }
  }
}

Fehlerbehandlung implementieren

TypeScript Beispiel

interface ApiError {
  code: string;
  message: string;
  details?: Record<string, unknown>;
}

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: ApiError;
  meta?: {
    requestId: string;
    timestamp: string;
  };
}

async function callApi<T>(
  url: string,
  options: RequestInit = {}
): Promise<T> {
  const response = await fetch(url, {
    ...options,
    headers: {
      "Authorization": `Bearer ${process.env.CODEFLUSS_API_KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  const json: ApiResponse<T> = await response.json();

  if (!json.success || json.error) {
    const error = json.error!;
    
    switch (error.code) {
      case "UNAUTHORIZED":
        throw new AuthenticationError(error.message);
      case "FORBIDDEN":
        throw new PermissionError(error.message, error.details);
      case "NOT_FOUND":
        throw new NotFoundError(error.message, error.details);
      case "VALIDATION_ERROR":
        throw new ValidationError(error.message, error.details);
      case "RATE_LIMIT_EXCEEDED":
        throw new RateLimitError(error.message, error.details);
      case "LIMIT_REACHED":
        throw new LimitReachedError(error.message, error.details);
      default:
        throw new ApiError(error.message, error.code, error.details);
    }
  }

  return json.data!;
}

Fehlerklassen

class ApiError extends Error {
  constructor(
    message: string,
    public code: string,
    public details?: Record<string, unknown>
  ) {
    super(message);
    this.name = "ApiError";
  }
}

class ValidationError extends ApiError {
  constructor(message: string, details?: Record<string, unknown>) {
    super(message, "VALIDATION_ERROR", details);
    this.name = "ValidationError";
  }
  
  get issues(): Array<{ field: string; message: string }> {
    return (this.details?.issues as Array<{ field: string; message: string }>) || [];
  }
}

class RateLimitError extends ApiError {
  constructor(message: string, details?: Record<string, unknown>) {
    super(message, "RATE_LIMIT_EXCEEDED", details);
    this.name = "RateLimitError";
  }
  
  get retryAfter(): number {
    return (this.details?.retryAfter as number) || 60;
  }
}

Request-ID für Support

Jede Response enthält eine eindeutige requestId im meta-Objekt:

{
  "meta": {
    "requestId": "req_1706054400_abc123",
    "timestamp": "2026-01-23T12:00:00Z"
  }
}

Bei Support-Anfragen geben Sie diese ID an, um schnellere Hilfe zu erhalten.

Nächste Schritte

Rate Limits – Verstehen Sie die Anfragelimits
Projekte – Erste API-Anfragen