> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolink.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference des Codes d'Erreur

> Liste complete des codes d'erreur de tache et guide de depannage

## Format de Reponse d'Erreur

Lorsqu'une tache echoue (`status: "failed"`), la reponse inclut un objet `error` :

```json theme={null}
{
  "id": "task-unified-1772618027-cmeisy8h",
  "object": "image.generation.task",
  "status": "failed",
  "model": "gemini-3.1-flash-image-preview",
  "progress": 0,
  "error": {
    "code": "content_policy_violation",
    "message": "Content policy violation.\nYour request was blocked by safety filters..."
  }
}
```

| Champ           | Type     | Description                                                     |
| --------------- | -------- | --------------------------------------------------------------- |
| `error.code`    | `string` | Identifiant du code d'erreur. Voir la liste complete ci-dessous |
| `error.message` | `string` | Description d'erreur conviviale avec conseils de depannage      |

***

## Apercu des Codes d'Erreur

<AccordionGroup>
  <Accordion title="Erreurs Client (Corrigibles par l'Utilisateur)" icon="user" defaultOpen>
    | Code d'Erreur              | Description                                                 | Reessayable                             |
    | -------------------------- | ----------------------------------------------------------- | --------------------------------------- |
    | `content_policy_violation` | Le contenu viole les politiques de securite                 | Corriger le contenu, puis reessayer     |
    | `invalid_parameters`       | Parametres de requete invalides                             | Corriger les parametres, puis reessayer |
    | `image_processing_error`   | Echec du traitement de l'image                              | Utiliser une autre image                |
    | `image_dimension_mismatch` | Les dimensions de l'image ne correspondent pas a la requete | Redimensionner l'image, puis reessayer  |
    | `request_cancelled`        | La requete a ete annulee                                    | Resoumettre                             |
  </Accordion>

  <Accordion title="Erreurs Serveur (Reessayer Plus Tard)" icon="server">
    | Code d'Erreur                  | Description                                 | Reessayable                                   |
    | ------------------------------ | ------------------------------------------- | --------------------------------------------- |
    | `generation_failed_no_content` | Le modele n'a pas pu generer de contenu     | Essayer un autre prompt                       |
    | `service_error`                | Erreur interne du service                   | Recuperation automatique, reessayer plus tard |
    | `generation_timeout`           | Le traitement de la tache a expire          | Reessayer plus tard                           |
    | `resource_exhausted`           | Ressources en amont temporairement epuisees | Recuperation automatique, reessayer plus tard |
    | `quota_exceeded`               | Limite de debit ou quota depasse            | Reduire la frequence, reessayer plus tard     |
    | `service_unavailable`          | Service temporairement indisponible         | Recuperation automatique, reessayer plus tard |
    | `resource_not_found`           | ID de tache invalide ou expire              | Verifier l'ID de tache                        |
    | `unknown_error`                | Erreur non classifiee                       | Contacter le support                          |
  </Accordion>
</AccordionGroup>

***

## Details des Codes d'Erreur

### content\_policy\_violation

<Card title="Violation de la Politique de Contenu" icon="shield-halved" color="#e74c3c">
  Votre requete a ete bloquee par les filtres de securite. C'est le **type d'erreur le plus courant**, couvrant les scenarios suivants :
</Card>

**Declencheurs courants :**

| Sous-type                        | Description                                                             | Message d'exemple                |
| -------------------------------- | ----------------------------------------------------------------------- | -------------------------------- |
| Personnes photorealistes         | L'image telechargee contient de vrais visages humains                   | `photorealistic people detected` |
| Ressemblance avec des celebrites | Implique des celebrites ou des personnalites publiques                  | `celebrity detected in image`    |
| Droit d'auteur/Marque            | Implique des logos de marque, des marques deposees ou de la PI protegee | `third-party content violation`  |
| Adulte/NSFW                      | Contient de la nudite ou du contenu sexuellement suggestif              | `nudity detected`                |
| Violence/Automutilation          | Contient du contenu violent, graphique ou d'automutilation              | `violence content blocked`       |
| Protection des mineurs           | Implique du contenu sensible lie aux mineurs                            | `minor content not allowed`      |
| Politique generale               | Autres violations de la politique de contenu                            | `content policy violation`       |

<Tip>
  **Comment eviter :**

  * Evitez de telecharger de vraies photos de personnes — utilisez des styles d'illustration ou de dessin anime
  * Supprimez les logos de marque, les marques deposees et les personnages de PI proteges
  * Evitez les themes adultes, violents ou d'automutilation
  * Utilisez des descriptions de personnages generiques (par exemple, "a person") au lieu de referencer des celebrites specifiques
</Tip>

***

### generation\_failed\_no\_content

<Card title="Echec de Generation" icon="image-slash" color="#e67e22">
  Le modele n'a pas pu produire de contenu pour votre requete. Bien que le format de la requete soit valide, le modele n'a pas pu generer de resultat pendant le traitement.
</Card>

**Causes courantes :**

* **Mauvaise qualite du prompt** : La description est trop vague ou contradictoire pour que le modele comprenne
* **Limites de capacite du modele** : Le prompt depasse les capacites de generation du modele
* **Problemes du service en amont** : Le service du modele sous-jacent a retourne un resultat vide
* **Detection de contenu protege** : Le prompt ou l'image de reference peut impliquer la suppression de filigranes ou du contenu protege (logos, marques, etc.)

<Tip>
  **Comment corriger :**

  * Ajustez votre prompt pour etre plus clair et specifique
  * Utilisez des images de reference differentes — evitez les images avec des filigranes ou des logos
  * Simplifiez la requete (resolution ou complexite inferieure)
  * Reessayez simplement — certains cas reussissent lors d'un nouvel essai
</Tip>

***

### invalid\_parameters

<Card title="Parametres Invalides" icon="sliders" color="#f39c12">
  Les parametres de la requete ne repondent pas aux exigences du modele.
</Card>

**Sous-types courants :**

| Sous-type               | Description                                                           | Exemple                                         |
| ----------------------- | --------------------------------------------------------------------- | ----------------------------------------------- |
| Prompt trop long        | Le prompt depasse la longueur maximale du modele                      | `Prompt is too long`                            |
| Dimension d'image       | La largeur/hauteur ou le rapport d'aspect de l'image est hors limites | `image dimensions must be between 240 and 7680` |
| Fichier trop volumineux | Le fichier telecharge depasse la limite de taille                     | `file size exceeds 10MB`                        |
| Format non supporte     | Le format du fichier telecharge n'est pas supporte                    | `unsupported file type`                         |
| Duree de video          | La duree de la video est hors de la plage supportee par le modele     | `Video duration must be between 1-30 seconds`   |

<Tip>
  **Comment corriger :**

  * Consultez la documentation API specifique au modele pour les exigences de parametres
  * Formats d'image supportes : JPG, PNG, WebP, GIF (HEIC, AVIF, TIFF **ne sont pas** supportes)
  * Limites de taille d'image : generalement \< 10 Mo, certains modeles \< 30 Mo
  * Raccourcissez votre prompt ou divisez les longs prompts en descriptions essentielles
</Tip>

***

### image\_processing\_error

<Card title="Echec du Traitement d'Image" icon="file-image" color="#9b59b6">
  Le systeme n'a pas pu traiter l'image d'entree.
</Card>

**Causes courantes :**

* L'URL de l'image n'est pas accessible (authentification requise, restrictions CDN, lien expire)
* Le format d'image n'est pas supporte (par exemple, HEIC, AVIF)
* Le fichier image est corrompu
* Des problemes de reseau ont empeche le telechargement de l'image

<Tip>
  **Comment corriger :**

  * Assurez-vous que l'URL de l'image est accessible publiquement sans authentification ni restrictions de region
  * Utilisez des formats standard : JPG, PNG, WebP
  * Essayez d'utiliser l'[API de telechargement de fichiers](/fr/api-manual/file-series/upload-base64) au lieu des URLs
  * Verifiez que l'image s'ouvre correctement dans un navigateur
</Tip>

***

### image\_dimension\_mismatch

<Card title="Inadequation des Dimensions de l'Image" icon="ruler-combined" color="#e74c3c">
  Les dimensions de l'image d'entree ne correspondent pas aux dimensions specifiees dans la requete. Courant dans les scenarios de conversion image vers video.
</Card>

**Exemple :**

* `aspect_ratio=1280x720` (16:9) necessite une image paysage de 1280x720
* `aspect_ratio=720x1280` (9:16) necessite une image portrait de 720x1280

<Tip>
  **Comment corriger :**
  Redimensionnez votre image pour correspondre au parametre `aspect_ratio` demande, ou modifiez le `aspect_ratio` pour correspondre a votre image.
</Tip>

***

### service\_error

<Card title="Erreur de Service" icon="server" color="#34495e">
  Un probleme interne s'est produit dans le service en amont. C'est generalement temporaire — le systeme bascule automatiquement vers d'autres routes disponibles.
</Card>

**Causes courantes :**

* Service du modele en amont temporairement indisponible
* Surcharge du serveur / trafic eleve
* Maintenance en cours
* Connexion reseau interrompue

<Tip>
  **Comment corriger :**

  * Attendez 30-60 secondes et reessayez — le systeme se retablit generalement automatiquement
  * Si le probleme persiste, contactez le support technique
  * Pas besoin de modifier votre requete — reessayez la meme requete
</Tip>

***

### generation\_timeout

<Card title="Delai de Generation Depasse" icon="clock" color="#e67e22">
  La tache ne s'est pas terminee dans le delai imparti.
</Card>

**Causes courantes :**

* Charge systeme elevee causant des retards dans la file d'attente
* Complexite elevee de la tache (haute resolution, longue video, etc.)
* Reponse lente du service en amont

<Tip>
  **Comment corriger :**

  * Reessayez plus tard, de preference pendant les heures creuses
  * Reduisez la complexite de la tache : resolution plus basse, duree de video plus courte
  * Simplifiez les descriptions du prompt
</Tip>

***

### quota\_exceeded

<Card title="Quota / Limite de Debit Depasse" icon="gauge-high" color="#e74c3c">
  Les limites de frequence de requete ou de concurrence ont ete depassees.
</Card>

**Causes courantes :**

* Trop de requetes envoyees en peu de temps (limitation de debit)
* Plusieurs taches en cours de traitement simultanement (limite de concurrence)
* Quota du compte epuise

<Tip>
  **Comment corriger :**

  * Reduisez la frequence des requetes — intervalle recommande de 1-2 secondes entre les requetes
  * Attendez que les taches en cours se terminent avant d'en soumettre de nouvelles
  * Si le quota est epuise, visitez la [page de facturation](https://evolink.ai/dashboard/billing) pour recharger
</Tip>

***

### resource\_exhausted

<Card title="Ressources Epuisees" icon="battery-empty" color="#c0392b">
  Les ressources de calcul du service en amont sont temporairement epuisees. Se produit generalement pendant les periodes de pointe d'utilisation du modele.
</Card>

<Tip>
  **Comment corriger :**

  * Attendez 1-5 minutes pour la recuperation automatique
  * Le systeme bascule automatiquement entre plusieurs routes — reessayer plus tard reussit generalement
</Tip>

***

### resource\_not\_found

<Card title="Ressource Non Trouvee" icon="magnifying-glass" color="#7f8c8d">
  L'ID de tache demande n'existe pas ou a expire.
</Card>

<Tip>
  **Comment corriger :**

  * Verifiez que l'ID de tache est correctement orthographie
  * Les resultats de tache ont une periode d'expiration — les taches expirees ne peuvent pas etre consultees
  * Si l'ID est correct, reessayez apres une courte attente
</Tip>

***

### request\_cancelled

<Card title="Requete Annulee" icon="ban" color="#95a5a6">
  La tache a ete annulee ou interrompue pendant le traitement.
</Card>

<Tip>
  Si vous n'avez pas intentionnellement annule, resoumettre simplement la meme requete.
</Tip>

***

### service\_unavailable

<Card title="Service Indisponible" icon="plug-circle-xmark" color="#e74c3c">
  Un probleme d'authentification ou de connexion interne s'est produit. Cette erreur a ete automatiquement enregistree et sera generalement resolue rapidement.
</Card>

<Tip>
  **Comment corriger :**

  * Attendez quelques minutes et reessayez
  * Si le probleme persiste, contactez le support technique avec votre ID de tache
</Tip>

***

### unknown\_error

<Card title="Erreur Inconnue" icon="question" color="#7f8c8d">
  Une erreur non classifiee. Le systeme n'a pas pu identifier le type d'erreur specifique.
</Card>

<Tip>
  **Comment corriger :**

  * Reessayez apres une courte attente
  * Si le probleme persiste, contactez le support technique avec l'ID de tache complet
</Tip>

***

## Bonnes Pratiques

### Exemple de Gestion des Erreurs

```python theme={null}
import requests
import time

def poll_task_with_retry(task_id, api_key, max_retries=3):
    """Poll task status with automatic retry for server errors"""
    headers = {"Authorization": f"Bearer {api_key}"}

    for attempt in range(max_retries):
        resp = requests.get(
            f"https://api.evolink.ai/v1/tasks/{task_id}",
            headers=headers
        )
        data = resp.json()

        if data["status"] == "completed":
            return data["results"]

        if data["status"] == "failed":
            error = data.get("error", {})
            code = error.get("code", "unknown_error")
            message = error.get("message", "")

            # Client errors — not retryable, fix the request
            if code in [
                "content_policy_violation",
                "invalid_parameters",
                "image_processing_error",
                "image_dimension_mismatch",
            ]:
                raise Exception(f"Client error [{code}]: {message}")

            # Server errors — retryable
            if code in [
                "generation_failed_no_content",
                "service_error",
                "generation_timeout",
                "resource_exhausted",
                "quota_exceeded",
            ]:
                if attempt < max_retries - 1:
                    wait = 2 ** attempt * 5  # 5s, 10s, 20s
                    time.sleep(wait)
                    continue
                raise Exception(f"Server error [{code}]: {message}")

            raise Exception(f"Error [{code}]: {message}")

        # Task still processing
        time.sleep(3)

    raise Exception("Max polling attempts exceeded")
```

### Reessayable vs Non Reessayable

<CardGroup cols={2}>
  <Card title="Corriger la Requete Avant de Reessayer" icon="pen">
    * `content_policy_violation` — Modifier le contenu
    * `invalid_parameters` — Corriger les parametres
    * `image_processing_error` — Utiliser une autre image
    * `image_dimension_mismatch` — Redimensionner l'image
  </Card>

  <Card title="Sur de Reessayer Directement" icon="rotate">
    * `generation_failed_no_content` — Essayer un autre prompt
    * `service_error` — Attendre, puis reessayer
    * `generation_timeout` — Attendre, puis reessayer
    * `resource_exhausted` — Recuperation automatique
    * `quota_exceeded` — Reduire la frequence, puis reessayer
  </Card>
</CardGroup>