Codes d’erreur courants de l’API

Comprendre les réponses d’erreur vous aide à résoudre les problèmes rapidement. Voici les erreurs les plus courantes que vous rencontrerez.

400 Requête incorrecte

{
  "error": "media_id is required"
}

Causes :

• Paramètre requis manquant

• Format de paramètre invalide

• JSON mal formé

Correction : Vérifiez que le corps de votre requête correspond à la spécification de l’API sur api.cathopic.com/docs.

401 Non autorisé

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

Causes :

• Clé API manquante ou invalide

• Clé API désactivée

• Mauvais nom d’en-tête

Correction : Vérifiez que votre en-tête x-api-key est correct et que la clé est active dans Paramètres → API.

404 Introuvable

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

Causes :

• La ressource n’existe pas

• La ressource a été supprimée

• Mauvais media_id

Correction : Vérifiez que le media_id existe en commençant par une recherche avec /resources.

429 Trop de requêtes

{
  "error": "Limit exceed."
}

Causes :

• Trop de requêtes sur une courte période

• Limite de débit dépassée

Correction : Mettez en place un backoff exponentiel. Attendez puis réessayez en augmentant progressivement les délais (1 s, 2 s, 4 s, etc.).

500 Erreur interne du serveur

{
  "error": "Internal server error"
}

Causes :

• Problème temporaire du serveur

• Condition inattendue

Correction : Attendez un instant puis réessayez. Si le problème persiste, contactez le support.

Exemple de gestion des erreurs

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('Unauthorized. Check your API key.');
          break;
        case 404:
          console.error('Resource not found:', error);
          break;
        case 429:
          console.error('Rate limited. Implementing backoff...');
          await sleep(5000);
          return searchWithErrorHandling(query); // Retry
        case 500:
          console.error('Server error. Retrying in 10s...');
          await sleep(10000);
          return searchWithErrorHandling(query);
        default:
          console.error('Unknown error:', error);
      }
      
      throw new Error(`API error: ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('Request failed:', error);
    throw error;
  }
}

En cas d’erreurs persistantes, consultez la documentation complète de l’API ou contactez le support.