> ## 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.

# Fehlercode-Referenz

> Vollstandige Liste der Aufgaben-Fehlercodes und Fehlerbehebungsleitfaden

## Fehlerantwortformat

Wenn eine Aufgabe fehlschlagt (`status: "failed"`), enthalt die Antwort ein `error`-Objekt:

```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..."
  }
}
```

| Feld            | Typ      | Beschreibung                                                    |
| --------------- | -------- | --------------------------------------------------------------- |
| `error.code`    | `string` | Fehlercode-Kennung. Siehe vollstandige Liste unten              |
| `error.message` | `string` | Benutzerfreundliche Fehlerbeschreibung mit Fehlerbehebungstipps |

***

## Fehlercode-Ubersicht

<AccordionGroup>
  <Accordion title="Client-Fehler (vom Benutzer behebbar)" icon="user" defaultOpen>
    | Fehlercode                 | Beschreibung                                      | Wiederholbar                                 |
    | -------------------------- | ------------------------------------------------- | -------------------------------------------- |
    | `content_policy_violation` | Inhalt verletzt Sicherheitsrichtlinien            | Inhalt andern, dann erneut versuchen         |
    | `invalid_parameters`       | Ungultige Anfrageparameter                        | Parameter korrigieren, dann erneut versuchen |
    | `image_processing_error`   | Bildverarbeitung fehlgeschlagen                   | Anderes Bild verwenden                       |
    | `image_dimension_mismatch` | Bildabmessungen stimmen nicht mit Anfrage uberein | Bild anpassen, dann erneut versuchen         |
    | `request_cancelled`        | Anfrage wurde abgebrochen                         | Erneut einreichen                            |
  </Accordion>

  <Accordion title="Server-Fehler (Spater erneut versuchen)" icon="server">
    | Fehlercode                     | Beschreibung                                     | Wiederholbar                                            |
    | ------------------------------ | ------------------------------------------------ | ------------------------------------------------------- |
    | `generation_failed_no_content` | Modell konnte keine Ausgabe erzeugen             | Anderen Prompt versuchen                                |
    | `service_error`                | Interner Servicefehler                           | Automatische Wiederherstellung, spater erneut versuchen |
    | `generation_timeout`           | Aufgabenverarbeitung hat Zeitlimit uberschritten | Spater erneut versuchen                                 |
    | `resource_exhausted`           | Upstream-Ressourcen vorubergehend erschopft      | Automatische Wiederherstellung, spater erneut versuchen |
    | `quota_exceeded`               | Ratenlimit oder Kontingent uberschritten         | Haufigkeit reduzieren, spater erneut versuchen          |
    | `service_unavailable`          | Dienst vorubergehend nicht verfugbar             | Automatische Wiederherstellung, spater erneut versuchen |
    | `resource_not_found`           | Aufgaben-ID ungultig oder abgelaufen             | Aufgaben-ID prufen                                      |
    | `unknown_error`                | Nicht klassifizierter Fehler                     | Support kontaktieren                                    |
  </Accordion>
</AccordionGroup>

***

## Fehlercode-Details

### content\_policy\_violation

<Card title="Inhaltspolitik-Verstoss" icon="shield-halved" color="#e74c3c">
  Ihre Anfrage wurde von Sicherheitsfiltern blockiert. Dies ist der **haufigste Fehlertyp**, der folgende Szenarien abdeckt:
</Card>

**Haufige Ausloser:**

| Untertyp                  | Beschreibung                                                      | Beispielmeldung                  |
| ------------------------- | ----------------------------------------------------------------- | -------------------------------- |
| Fotorealistische Personen | Hochgeladenes Bild enthalt echte Gesichter                        | `photorealistic people detected` |
| Prominente                | Betrifft Prominente oder offentliche Personen                     | `celebrity detected in image`    |
| Urheberrecht/Marke        | Betrifft Markenlogos, Marken oder urheberrechtlich geschutztes IP | `third-party content violation`  |
| Erwachsene/NSFW           | Enthalt Nacktheit oder sexuell anzugliche Inhalte                 | `nudity detected`                |
| Gewalt/Selbstverletzung   | Enthalt gewaltatige, grafische oder selbstverletzende Inhalte     | `violence content blocked`       |
| Minderjahrigenschutz      | Betrifft sensible Inhalte im Zusammenhang mit Minderjahrigen      | `minor content not allowed`      |
| Allgemeine Richtlinie     | Andere Inhaltspolitik-Verstesse                                   | `content policy violation`       |

<Tip>
  **So vermeiden Sie dies:**

  * Vermeiden Sie das Hochladen echter Personenfotos — verwenden Sie stattdessen Illustrations- oder Cartoon-Stile
  * Entfernen Sie Markenlogos, Marken und urheberrechtlich geschutzte IP-Charaktere
  * Vermeiden Sie Erwachsenen-, Gewalt- oder Selbstverletzungsthemen
  * Verwenden Sie generische Charakterbeschreibungen (z.B. "a person") anstelle von Verweisen auf bestimmte Prominente
</Tip>

***

### generation\_failed\_no\_content

<Card title="Generierung fehlgeschlagen" icon="image-slash" color="#e67e22">
  Das Modell konnte fur Ihre Anfrage keine Ausgabe erzeugen. Obwohl das Anfrageformat gultig war, konnte das Modell wahrend der Verarbeitung kein Ergebnis erzeugen.
</Card>

**Haufige Ursachen:**

* **Schlechte Prompt-Qualitat**: Beschreibung ist zu vage oder widerspuchlich
* **Modellfahigkeitsgrenzen**: Der Prompt ubersteigt die Generierungsfahigkeiten des Modells
* **Upstream-Dienstprobleme**: Der zugrunde liegende Modelldienst hat ein leeres Ergebnis zuruckgegeben
* **Geschutzter Inhalt erkannt**: Der Prompt oder das Referenzbild kann Wasserzeichenentfernung oder geschutzte Inhalte (Logos, Marken usw.) betreffen

<Tip>
  **So beheben Sie dies:**

  * Passen Sie Ihren Prompt an, um ihn klarer und spezifischer zu machen
  * Verwenden Sie andere Referenzbilder — vermeiden Sie Bilder mit Wasserzeichen oder Logos
  * Vereinfachen Sie die Anfrage (niedrigere Auflosung oder Komplexitat)
  * Einfach erneut versuchen — einige Falle sind beim erneuten Versuch erfolgreich
</Tip>

***

### invalid\_parameters

<Card title="Ungultige Parameter" icon="sliders" color="#f39c12">
  Anfrageparameter entsprechen nicht den Modellanforderungen.
</Card>

**Haufige Untertypen:**

| Untertyp                   | Beschreibung                                                   | Beispiel                                        |
| -------------------------- | -------------------------------------------------------------- | ----------------------------------------------- |
| Prompt zu lang             | Prompt uberschreitet maximale Lange des Modells                | `Prompt is too long`                            |
| Bildabmessung              | Bildbreite/-hohe oder Seitenverhaltnis ausserhalb des Bereichs | `image dimensions must be between 240 and 7680` |
| Datei zu gross             | Hochgeladene Datei uberschreitet Grossenlimit                  | `file size exceeds 10MB`                        |
| Nicht unterstutztes Format | Hochgeladenes Dateiformat wird nicht unterstutzt               | `unsupported file type`                         |
| Videodauer                 | Videodauer ausserhalb des unterstutzten Bereichs des Modells   | `Video duration must be between 1-30 seconds`   |

<Tip>
  **So beheben Sie dies:**

  * Prufen Sie die modellspezifische API-Dokumentation fur Parameteranforderungen
  * Unterstutzte Bildformate: JPG, PNG, WebP, GIF (HEIC, AVIF, TIFF werden **nicht** unterstutzt)
  * Bildgrossenlimits: typischerweise \< 10MB, einige Modelle \< 30MB
  * Kurzen Sie Ihren Prompt oder teilen Sie lange Prompts in Kernbeschreibungen auf
</Tip>

***

### image\_processing\_error

<Card title="Bildverarbeitung fehlgeschlagen" icon="file-image" color="#9b59b6">
  Das System konnte das Eingabebild nicht verarbeiten.
</Card>

**Haufige Ursachen:**

* Bild-URL ist nicht zuganglich (Authentifizierung erforderlich, CDN-Einschrankungen, abgelaufener Link)
* Bildformat wird nicht unterstutzt (z.B. HEIC, AVIF)
* Bilddatei ist beschadigt
* Netzwerkprobleme verhinderten den Bilddownload

<Tip>
  **So beheben Sie dies:**

  * Stellen Sie sicher, dass die Bild-URL offentlich zuganglich ist, ohne Authentifizierung oder Regionseinschrankungen
  * Verwenden Sie Standardformate: JPG, PNG, WebP
  * Versuchen Sie die [Datei-Upload-API](/de/api-manual/file-series/upload-base64) anstelle von URLs
  * Uberprufen Sie, ob das Bild im Browser korrekt geoffnet wird
</Tip>

***

### image\_dimension\_mismatch

<Card title="Bildabmessungen stimmen nicht uberein" icon="ruler-combined" color="#e74c3c">
  Die Eingabebildabmessungen stimmen nicht mit den in der Anfrage angegebenen Abmessungen uberein. Haufig bei Bild-zu-Video-Szenarien.
</Card>

**Beispiel:**

* `aspect_ratio=1280x720` (16:9) erfordert ein 1280x720 Querformatbild
* `aspect_ratio=720x1280` (9:16) erfordert ein 720x1280 Hochformatbild

<Tip>
  **So beheben Sie dies:**
  Andern Sie die Grosse Ihres Bildes, um den angeforderten `aspect_ratio`-Parameter anzupassen, oder andern Sie `aspect_ratio`, um Ihrem Bild zu entsprechen.
</Tip>

***

### service\_error

<Card title="Dienstfehler" icon="server" color="#34495e">
  Ein internes Problem trat im Upstream-Dienst auf. Dies ist normalerweise vorubergehend — das System wechselt automatisch zu anderen verfugbaren Routen.
</Card>

**Haufige Ursachen:**

* Upstream-Modelldienst vorubergehend nicht verfugbar
* Server-Uberlastung / hoher Datenverkehr
* Wartung in Bearbeitung
* Netzwerkverbindung unterbrochen

<Tip>
  **So beheben Sie dies:**

  * Warten Sie 30-60 Sekunden und versuchen Sie es erneut — das System erholt sich normalerweise automatisch
  * Bei anhaltenden Problemen wenden Sie sich an den technischen Support
  * Keine Anderung Ihrer Anfrage erforderlich — versuchen Sie dieselbe Anfrage erneut
</Tip>

***

### generation\_timeout

<Card title="Generierungs-Zeituberschreitung" icon="clock" color="#e67e22">
  Die Aufgabe wurde nicht innerhalb der erlaubten Zeit abgeschlossen.
</Card>

**Haufige Ursachen:**

* Hohe Systemauslastung verursacht Warteschlangeverzogerungen
* Hohe Aufgabenkomplexitat (hohe Auflosung, langes Video usw.)
* Langsame Upstream-Dienst-Antwort

<Tip>
  **So beheben Sie dies:**

  * Spater erneut versuchen, vorzugsweise wahrend der Nebenzeiten
  * Aufgabenkomplexitat reduzieren: niedrigere Auflosung, kurzere Videodauer
  * Prompt-Beschreibungen vereinfachen
</Tip>

***

### quota\_exceeded

<Card title="Kontingent / Ratenlimit uberschritten" icon="gauge-high" color="#e74c3c">
  Anfragehaufigkeit oder Gleichzeitigkeitslimits wurden uberschritten.
</Card>

**Haufige Ursachen:**

* Zu viele Anfragen in kurzer Zeit gesendet (Ratenlimitierung)
* Mehrere Aufgaben werden gleichzeitig verarbeitet (Gleichzeitigkeitslimit)
* Kontokontingent erschopft

<Tip>
  **So beheben Sie dies:**

  * Anfragehaufigkeit reduzieren — empfohlenes Intervall von 1-2 Sekunden zwischen Anfragen
  * Warten Sie, bis laufende Aufgaben abgeschlossen sind, bevor Sie neue einreichen
  * Wenn das Kontingent erschopft ist, besuchen Sie die [Abrechnungsseite](https://evolink.ai/dashboard/billing) zum Aufladen
</Tip>

***

### resource\_exhausted

<Card title="Ressourcen erschopft" icon="battery-empty" color="#c0392b">
  Die Rechenressourcen des Upstream-Dienstes sind vorubergehend erschopft. Tritt normalerweise wahrend Spitzennutzungszeiten des Modells auf.
</Card>

<Tip>
  **So beheben Sie dies:**

  * 1-5 Minuten warten fur automatische Wiederherstellung
  * Das System wechselt automatisch zwischen mehreren Routen — spateres Erneut-Versuchen ist normalerweise erfolgreich
</Tip>

***

### resource\_not\_found

<Card title="Ressource nicht gefunden" icon="magnifying-glass" color="#7f8c8d">
  Die angeforderte Aufgaben-ID existiert nicht oder ist abgelaufen.
</Card>

<Tip>
  **So beheben Sie dies:**

  * Uberprufen Sie, ob die Aufgaben-ID korrekt geschrieben ist
  * Aufgabenergebnisse haben eine Ablaufrist — abgelaufene Aufgaben konnen nicht abgefragt werden
  * Wenn die ID korrekt ist, versuchen Sie es nach einer kurzen Wartezeit erneut
</Tip>

***

### request\_cancelled

<Card title="Anfrage abgebrochen" icon="ban" color="#95a5a6">
  Die Aufgabe wurde wahrend der Verarbeitung abgebrochen oder unterbrochen.
</Card>

<Tip>
  Wenn Sie nicht absichtlich abgebrochen haben, reichen Sie einfach dieselbe Anfrage erneut ein.
</Tip>

***

### service\_unavailable

<Card title="Dienst nicht verfugbar" icon="plug-circle-xmark" color="#e74c3c">
  Ein internes Authentifizierungs- oder Verbindungsproblem ist aufgetreten. Dieser Fehler wurde automatisch protokolliert und wird typischerweise schnell behoben.
</Card>

<Tip>
  **So beheben Sie dies:**

  * Warten Sie einige Minuten und versuchen Sie es erneut
  * Bei anhaltenden Problemen wenden Sie sich mit Ihrer Aufgaben-ID an den technischen Support
</Tip>

***

### unknown\_error

<Card title="Unbekannter Fehler" icon="question" color="#7f8c8d">
  Ein nicht klassifizierter Fehler. Das System konnte den spezifischen Fehlertyp nicht identifizieren.
</Card>

<Tip>
  **So beheben Sie dies:**

  * Nach einer kurzen Wartezeit erneut versuchen
  * Wenn das Problem weiterhin besteht, wenden Sie sich mit der vollstandigen Aufgaben-ID an den technischen Support
</Tip>

***

## Best Practices

### Beispiel fur Fehlerbehandlung

```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")
```

### Wiederholbar vs Nicht wiederholbar

<CardGroup cols={2}>
  <Card title="Anfrage vor erneutem Versuch andern" icon="pen">
    * `content_policy_violation` — Inhalt andern
    * `invalid_parameters` — Parameter korrigieren
    * `image_processing_error` — Anderes Bild verwenden
    * `image_dimension_mismatch` — Bild anpassen
  </Card>

  <Card title="Direkt erneut versuchbar" icon="rotate">
    * `generation_failed_no_content` — Anderen Prompt versuchen
    * `service_error` — Warten, dann erneut versuchen
    * `generation_timeout` — Warten, dann erneut versuchen
    * `resource_exhausted` — Automatische Wiederherstellung
    * `quota_exceeded` — Haufigkeit reduzieren, dann erneut versuchen
  </Card>
</CardGroup>