Häufige API-Fehlercodes - Hilfecenter

Das Verstehen von Fehlerantworten hilft Ihnen, Probleme schnell zu beheben. Hier sind die häufigsten Fehler, denen Sie begegnen werden.

400 Bad Request

{
  "error": "media_id is required"
}

Ursachen:

Fehlender erforderlicher Parameter
Ungültiges Parameterformat
Fehlerhaftes JSON

Behebung: Prüfen Sie, ob Ihr Request-Body der API-Spezifikation entspricht unter api.cathopic.com/docs.

401 Unauthorized

{
  "message": "Unauthorized"
}
oder
{
  "error": "Unauthorized token"
}

Ursachen:

Fehlender oder ungültiger API-Schlüssel
Deaktivierter API-Schlüssel
Falscher Header-Name

Behebung: Vergewissern Sie sich, dass Ihr x-api-key-Header korrekt ist und der Schlüssel aktiv ist in Einstellungen → API.

404 Not Found

{
  "error": "No file found for media_id 1234"
}
oder
{
  "error": "Media item not found"
}

Ursachen:

Ressource existiert nicht
Ressource wurde gelöscht
Falsches media_id

Behebung: Prüfen Sie, ob die media_id existiert, indem Sie zuerst mit /resources suchen.

429 Too Many Requests

{
  "error": "Limit exceed."
}

Ursachen:

Zu viele Requests in kurzer Zeit
Rate-Limit überschritten

Behebung: Implementieren Sie exponentielles Backoff. Warten Sie und versuchen Sie es erneut mit zunehmenden Verzögerungen (1s, 2s, 4s usw.).

500 Internal Server Error

{
  "error": "Internal server error"
}

Ursachen:

Vorübergehendes Serverproblem
Unerwartete Bedingung

Behebung: Warten Sie einen Moment und versuchen Sie es erneut. Wenn das Problem weiterhin besteht, kontaktieren Sie den Support.

Beispiel für Fehlerbehandlung

async function searchWithErrorHandling(query) {
  try {
    const response = await fetch('https://api.cathopic.com/resources', {
      method: 'POST',
      headers: {
        'x-api-key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ query, page: 1, page_size: 20 })
    });
    
    if (!response.ok) {
      const error = await response.json();
      
      switch (response.status) {
        case 400:
          console.error('Bad request:', error);
          break;
        case 401:
          console.error('Nicht autorisiert. Prüfen Sie Ihren API-Schlüssel.');
          break;
        case 404:
          console.error('Ressource nicht gefunden:', error);
          break;
        case 429:
          console.error('Rate-Limit erreicht. Backoff wird implementiert...');
          await sleep(5000);
          return searchWithErrorHandling(query); // Retry
        case 500:
          console.error('Serverfehler. Erneut versuchen in 10s...');
          await sleep(10000);
          return searchWithErrorHandling(query);
        default:
          console.error('Unbekannter Fehler:', error);
      }
      
      throw new Error(`API error: ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('Request fehlgeschlagen:', error);
    throw error;
  }
}

Bei anhaltenden Fehlern prüfen Sie die vollständige API-Dokumentation oder kontaktieren Sie den Support.