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

# Fehlerbehandlung

> Umfassender Leitfaden zu Fehlercodes und Fehlerbehebung für Topsort-APIs

# Fehler

Bei der Arbeit mit Topsort-APIs können verschiedene Fehlerantworten auftreten. Dieser Leitfaden hilft Ihnen, häufige Probleme zu verstehen, zu diagnostizieren und zu beheben.

## Fehlerantwortformat

Topsort-APIs geben Fehler als JSON-Arrays zurück, die Fehlerobjekte enthalten:

| Feld      | Typ    | Beschreibung                                                             |
| :-------- | :----- | :----------------------------------------------------------------------- |
| `errCode` | string | Kurze Zeichenfolge, die das Problem eindeutig identifiziert              |
| `docUrl`  | string | Link zur Dokumentation mit weiteren Informationen                        |
| `message` | string | Optionale menschenlesbare Erklärung (kann sich im Laufe der Zeit ändern) |

## HTTP-Statuscodes

<CardGroup cols={2}>
  <Card title="400 - Bad Request" icon="circle-exclamation">
    Inakzeptables Anforderungsformat oder falsche Syntax. Überprüfen Sie die Anforderungsstruktur anhand der API-Spezifikation.
  </Card>

  <Card title="403 - Forbidden" icon="lock">
    API-Schlüsselproblem oder fehlende Autorisierungstoken. Überprüfen Sie Ihre Authentifizierungsdaten.
  </Card>

  <Card title="404 - Not Found" icon="file-slash">
    Ressource existiert nicht oder URL ist falsch. Überprüfen Sie den Endpunktpfad und die Ressourcen-ID.
  </Card>

  <Card title="422 - Unprocessable Entity" icon="file-circle-xmark">
    Anforderungstext entspricht nicht dem erwarteten Modell. Erforderliche Felder fehlen oder falsche Datentypen.
  </Card>

  <Card title="429 - Rate Limit" icon="gauge-high">
    Zu viele Anfragen. Überprüfen Sie die Rate-Limit-Header: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
  </Card>

  <Card title="5xx - Server Error" icon="server">
    Unerwartetes Serverproblem. Unser Team behebt diese Probleme normalerweise schnell. Überprüfen Sie die Statusseite.
  </Card>
</CardGroup>

## Spezifische Fehlercodes

<AccordionGroup>
  <Accordion title="Authentifizierungsfehler">
    * **`invalid_api_key`** - Der API-Schlüssel im Autorisierungsheader fehlt, ist ungültig oder abgelaufen. Siehe [Authentifizierung](/de/api-reference/authentication) für Details.
  </Accordion>

  <Accordion title="Anforderungsformatfehler">
    * **`bad_request`** - Die Anforderung konnte nicht geparst werden
    * **`invalid_json`** - Die Anforderung ist kein gültiges JSON
    * **`empty_request`** - Anforderungstext ist leer; stellen Sie sicher, dass Sie Daten senden
    * **`request_canceled`** - Der Aufrufer hat die Anforderung abgebrochen
    * **`invalid_operation`** - Die Operation ist im aktuellen Zustand nicht gültig
  </Accordion>

  <Accordion title="Auktionsfehler">
    * **`missing_auctions`** - Sie müssen mindestens eine Auktion angeben
    * **`too_many_auctions`** - Höchstens 5 Auktionen können parallel ausgeführt werden
    * **`too_few_slots`** - Mindestens ein Slot muss in einer Auktion angegeben werden
    * **`missing_slots`** - Erforderliches Slots-Feld fehlt
    * **`invalid_auction_id`** - Auktions-ID entspricht keiner gültigen Auktion
    * **`missing_promotion_type`** - Muss Slots für mindestens einen Promotion-Typ anfordern
    * **`invalid_promotion_type`** - Ungültige Promotion-Typen im Slots-Feld
  </Accordion>

  <Accordion title="Kontext- & Platzierungsfehler">
    * **`invalid_context`** - Ungültiger Kontext. Muss höchstens zwei von folgenden angeben: Produktliste, Suchanfrage oder Kategorien (für Sponsored Brands: höchstens eine)
    * **`invalid_placement_id`** - Platzierungs-ID muss zwischen 1 und 8 liegen
    * **`missing_slot_id`** - Fehlende erforderliche Slot-ID für Banner-Anzeigen
  </Accordion>

  <Accordion title="Kategoriefehler">
    * **`invalid_category`** - Nur eines von `id`, `ids` oder `disjunctions` muss gesetzt sein, wobei kein Array länger als 5 ist
  </Accordion>

  <Accordion title="Sitzungsfehler">
    * **`invalid_opaque_user_id`** - Wert der undurchsichtigen Benutzer-ID darf nicht länger als 90 Zeichen sein
  </Accordion>

  <Accordion title="Produkt- & Katalogfehler">
    * **`no_products`** - Mindestens ein Produkt muss angegeben werden
    * **`no_products_or_category`** - Entweder mindestens eine Produkt-ID oder eine Kategorie-ID muss angegeben werden
    * **`too_many_products`** - Limit der Produkte in der Anforderung überschritten
    * **`product_info_mismatch`** - Produktinformations-Arrays müssen alle die gleiche Länge haben
    * **`invalid_quality_score`** - Qualitätswerte müssen zwischen 0.0 und 1.0 liegen
    * **`non_positive_price`** - Produktpreis muss positiv sein
  </Accordion>

  <Accordion title="Geo-Targeting-Fehler">
    * **`invalid_geo_targeting`** - Ungültiges Geo-Targeting. Muss entweder `location` oder `locations` angeben
    * **`too_many_locations`** - Höchstens 2 Standorte können angegeben werden
    * **`invalid_location_cell`** - Angegebene Standortzelle ist keine gültige H3-Zelle
  </Accordion>

  <Accordion title="Gerätefehler">
    * **`invalid_device`** - Das Gerät muss eines von sein: `desktop` oder `mobile`
  </Accordion>

  <Accordion title="Suchfehler">
    * **`too_many_search_query_words`** - Limit der Suchanfragewörter in der Anforderung überschritten
  </Accordion>

  <Accordion title="Event-Tracking-Fehler">
    * **`invalid_event_time`** - Mindestens ein Event liegt in der Zukunft
    * **`invalid_resolved_bid_id`** - Ungültige resolvedBidId
    * **`invalid_use_of_external_campaign_id`** - Kann nicht sowohl `resolvedBidId` als auch `externalCampaignId` setzen
  </Accordion>

  <Accordion title="Kaufevent-Fehler">
    * **`no_purchase_items`** - Mindestens ein Artikel muss gekauft werden
    * **`missing_purchased_at`** - Erforderliches `purchasedAt`-Feld fehlt
  </Accordion>

  <Accordion title="Marketplace- & Anbieterfehler">
    * **`invalid_marketplace`** - Kein solcher Marketplace existiert
    * **`invalid_vendor`** - Kein solcher Anbieter existiert
    * **`resource_not_found`** - Die angeforderte Ressource wurde nicht gefunden
  </Accordion>

  <Accordion title="Experimentfehler">
    * **`experiment_variant_too_long`** - Marketplace-Experimentvarianten haben eine maximale Länge von 10 Zeichen
  </Accordion>

  <Accordion title="Hauptbuch- & Kontofehler">
    * **`account_unique_violation`** - Anforderung verletzt eindeutige Hauptbuchkonto-Einschränkung
    * **`invalid_ledger_account`** - Hauptbuchkonto existiert nicht
    * **`insufficient_balance`** - Unzureichender Saldo
    * **`different_currencies`** - Beide Konten müssen denselben Währungscode haben
    * **`equal_from_and_to`** - From und To müssen unterschiedlich sein
  </Accordion>

  <Accordion title="Filterfehler">
    * **`bad_request`** (Filteroperation) - Die Filteroperation kann `and` oder `or` sein
    * **`bad_request`** (Attribute) - Die Anzahl der Filterattribute muss zwischen 1 und 3 liegen
    * **`bad_request`** (Promotions) - Die Anzahl der Filter-Promotions muss zwischen 1 und 3 liegen
  </Accordion>

  <Accordion title="Travel-API-Fehler">
    * **`invalid_travel_category`** - Reisekategorie muss eine nicht leere Zeichenfolge sein, wenn angegeben
    * **`invalid_travel_date_range`** - Enddatum muss größer als Startdatum sein
    * **`too_many_passengers`** - Anzahl der Passagiere muss kleiner als zehn sein
    * **`invalid_traveler_type`** - Reisender-Typ muss einer von sein: `family`, `group`, `solo`, `couple`
    * **`invalid_date_format`** - Datum muss dem Format `YYYY-MM-DD` folgen (z.B. 2012-05-08)
    * **`invalid_travel_type`** - Typ muss einer von sein: `hotels`, `flights`
    * **`missing_variation_id`** - Fehlende Variations-ID
    * **`missing_flight_travel_context`** - Fehlende Felder aus Flug-Reisekontext
  </Accordion>

  <Accordion title="Serverfehler">
    * **`internal_server_error`** - Der Server hat ein Problem festgestellt
    * **`request_canceled`** - Der Aufrufer hat die Anforderung abgebrochen
  </Accordion>
</AccordionGroup>

## Häufige Integrationsprobleme

<CardGroup cols={2}>
  <Card title="Events werden nicht angezeigt" icon="eye-slash">
    **Events geben 200 zurück, erscheinen aber nicht im Dashboard:**

    * Überprüfen Sie, dass `occurredAt` innerhalb der letzten 30 Tage liegt
    * Überprüfen Sie, dass das Produkt im Katalog existiert
    * Bestätigen Sie die Schreibweise des Event-Typs (`click`, nicht `Click`)
  </Card>

  <Card title="Leere Auktionsergebnisse" icon="rectangle-xmark">
    **Auktionen geben keine Gewinner zurück:**

    * **Überprüfen Sie das Kampagnenbudget** (häufigstes Problem)
    * **Überprüfen Sie, dass der Kontostand positiv ist**
    * Bestätigen Sie, dass Produkte auf Lager und aktiv sind
    * Überprüfen Sie, dass aktive Kampagnen existieren
    * Überprüfen Sie, dass Gebotsbeträge nicht zu niedrig sind
  </Card>

  <Card title="Attributionsprobleme" icon="link-slash">
    **Attribution funktioniert nicht korrekt:**

    * Siehe unseren [Attribution Troubleshooting Guide](/knowledge-base/ad-platform/reporting/attribution-troubleshooting)
    * Überprüfen Sie, dass aufgelöste Gebots-IDs korrekt übergeben werden
    * Überprüfen Sie, dass Kaufevents die richtigen Produkt-IDs enthalten
  </Card>

  <Card title="Verbindungsprobleme" icon="wifi-slash">
    **Verbindung abgelehnt oder Timeout:**

    * Testen Sie die Konnektivität: `curl -I https://api.topsort.com`
    * Überprüfen Sie, dass die Firewall ausgehendes HTTPS (Port 443) zulässt
    * Setzen Sie `*.topsort.com`-Domains auf die Whitelist
    * Überprüfen Sie die TLS/SSL-Zertifikatsvalidierung
  </Card>
</CardGroup>

<Warning>
  **Budgeterschöpfung ist die #1 Ursache für leere Auktionen.** Bevor Sie komplexe Auktionsprobleme debuggen, überprüfen Sie zunächst, dass Ihre Kampagnen ausreichendes Tagesbudget und Kontostand haben. Kampagnen mit null Budget können nicht an Auktionen teilnehmen.
</Warning>

## Detaillierte Validierungsfehler

Einige Endpunkte geben detaillierte Validierungsfehler mit Feldebeneninformationen zurück:

```json theme={null}
{
  "error": "validation_error",
  "message": "Invalid request body",
  "details": [
    {
      "field": "events[0].productId",
      "message": "Product 'sku_999' not found in catalog"
    },
    {
      "field": "events[0].occurredAt",
      "message": "Timestamp cannot be in the future"
    }
  ]
}
```

Verwenden Sie das `details`-Array, um genau zu identifizieren, welche Felder Probleme haben und was korrigiert werden muss.

## Rate Limiting

<CardGroup cols={2}>
  <Card title="Exponential Backoff" icon="arrows-rotate">
    Wiederholen Sie fehlgeschlagene Anfragen mit zunehmenden Verzögerungen zwischen Versuchen:

    ```python theme={null}
    def retry_with_backoff(url, max_retries=5):
        delay = 1
        for i in range(max_retries):
            response = requests.get(url)
            if response.status_code != 429:
                return response
            time.sleep(delay)
            delay = min(delay * 2, 64)
    ```
  </Card>

  <Card title="Rate-Limit-Header verwenden" icon="gauge">
    Beachten Sie die Rate-Limit-Header in Antworten:

    * `X-RateLimit-Limit` - Gesamtzahl erlaubter Anfragen
    * `X-RateLimit-Remaining` - Verbleibende Anfragen
    * `X-RateLimit-Reset` - Wann das Limit zurückgesetzt wird

    Warten Sie bis `X-RateLimit-Reset`, bevor Sie es erneut versuchen.
  </Card>
</CardGroup>

<Note>
  Auktionen (`/v2/auctions`) und Events (`/v2/events`) Endpunkte sind **nicht rate-limitiert**. Rate Limits gelten für andere Endpunkte wie Kampagnenverwaltungs- und Reporting-APIs.
</Note>

## Verbindungs- & Netzwerkprobleme

### Troubleshooting-Checkliste

<Steps>
  <Step title="Grundlegende Konnektivität testen">
    Überprüfen Sie, ob Sie die Topsort-API erreichen können:

    ```bash theme={null}
    curl -I https://api.topsort.com
    ```
  </Step>

  <Step title="Firewall-Regeln überprüfen">
    Stellen Sie sicher, dass ausgehender HTTPS-Verkehr (Port 443) erlaubt ist und setzen Sie auf die Whitelist:

    * `api.topsort.com`
    * `*.topsort.com`
  </Step>

  <Step title="TLS-Unterstützung überprüfen">
    Stellen Sie sicher, dass Ihr HTTP-Client moderne TLS-Versionen unterstützt:

    ```bash theme={null}
    openssl s_client -connect api.topsort.com:443
    ```
  </Step>

  <Step title="Timeouts konfigurieren">
    Setzen Sie geeignete Timeout-Werte und implementieren Sie Wiederholungslogik:

    ```python theme={null}
    session = requests.Session()
    session.timeout = (10, 30)  # (connect, read)
    ```
  </Step>

  <Step title="Statusseite überprüfen">
    Besuchen Sie [topsort.statuspage.io](https://topsort.statuspage.io) für Servicestatus
  </Step>
</Steps>

### Häufige Netzwerkprobleme

<AccordionGroup>
  <Accordion title="SSL/TLS-Zertifikatsprobleme">
    **Symptome:** Zertifikatsvalidierungsfehler, SSL-Handshake-Fehler

    **Lösungen:**

    * Aktualisieren Sie Ihren HTTP-Client, um moderne TLS-Versionen zu unterstützen
    * Stellen Sie sicher, dass Ihr System Standard-Zertifizierungsstellen vertraut
    * Testen Sie mit: `openssl s_client -connect api.topsort.com:443`
  </Accordion>

  <Accordion title="Firewall/Proxy-Probleme">
    **Symptome:** Verbindung abgelehnt, Anfragen hängen

    **Lösungen:**

    * Setzen Sie Topsort-Domains auf die Whitelist (`api.topsort.com`, `*.topsort.com`)
    * Erlauben Sie ausgehenden HTTPS-Verkehr auf Port 443
    * Konfigurieren Sie Proxy-Einstellungen, falls von Ihrem Netzwerk erforderlich
    * Testen Sie ohne Proxy, um das Problem zu isolieren
  </Accordion>

  <Accordion title="Timeout-Probleme">
    **Symptome:** Anfragen laufen in Timeout, hängen auf unbestimmte Zeit

    **Lösungen:**

    * Erhöhen Sie Timeout-Werte in Ihrem HTTP-Client
    * Implementieren Sie Wiederholungslogik mit exponentiellem Backoff
    * Überprüfen Sie auf große Anforderungsnutzlasten, die Limits überschreiten
    * Verwenden Sie Connection Pooling für bessere Leistung
  </Accordion>

  <Accordion title="Regionale Konnektivität">
    **Symptome:** Probleme aus bestimmten geografischen Regionen

    **Lösungen:**

    * Testen Sie von verschiedenen Standorten aus, um regionale Probleme zu isolieren
    * Verwenden Sie einen CDN- oder Proxy-Service bei Bedarf
    * Kontaktieren Sie den Support mit Ihren Standortdetails
  </Accordion>
</AccordionGroup>

## Debugging-Tools

<CardGroup cols={2}>
  <Card title="Entwicklerprotokolle" icon="list-check">
    Überprüfen Sie die **Dev Tools**-Registerkarte in Ihrer Ad Platform für detaillierte API-Anforderungs-/Antwortprotokolle.

    Siehe unseren [Entwicklerprotokolle-Leitfaden](/api-reference/logs) für Hilfe beim Interpretieren von Protokolleinträgen.
  </Card>

  <Card title="Statusseite" icon="signal">
    Überwachen Sie Service-Health und geplante Wartung unter [topsort.statuspage.io](https://topsort.statuspage.io)

    Abonnieren Sie Updates für Echtzeitbenachrichtigungen.
  </Card>
</CardGroup>

## Benötigen Sie Hilfe?

Wenn Sie nach Konsultation dieses Leitfadens weiterhin Probleme haben:

* **Überprüfen Sie die Statusseite:** [topsort.statuspage.io](https://topsort.statuspage.io)
* **Kontaktieren Sie den Support** mit Fehlerdetails und API-Anforderungsbeispielen
* **Überprüfen Sie die API-Dokumentation** für endpunktspezifische Anforderungen