# OpenAPI-Abrechnung und Fehler

Verstehe Plattform-Guthaben, Anfragen- und Ergebnisgebühren, seitenbasierte Abrechnung und sichere Wiederholungen.

Diese Seite gilt für `/api/v1/data/*`, die exklusiven OpenAPI-Platform-APIs von Felo. Aufrufe verwenden **Plattform-Guthaben**, ein in USD denominiertes Service-Credit-Guthaben. Sie verbrauchen kein Felo-Pro-Guthaben. Die älteren [Felo APIs](https://openapi.felo.ai/de/docs/api-reference/felo-apis.md) unter `/v2` verwenden Pro-Guthaben.

## Aktuelle Preise lesen

```bash
curl -sS https://openapi.felo.ai/api/v1/data/prices
```

Dieser öffentliche Endpunkt benötigt keinen Schlüssel. Ordne seine Einträge nach Operations-ID und lies den aktuellen Tarif sowie die Abrechnungseinheit; gehe nicht davon aus, dass jede Operation gleich viel kostet oder dass du einen Tarif aus einem Beispiel unverändert in deine Anwendung übernimmst.

| Operations-ID | Abrechnungseinheit |
|---|---|
| `web.search`, `web.read`, `chat` | Anfrage |
| `x.user.info`, `x.user.search`, `x.user.tweets`, `x.tweet.search`, `x.tweet.replies` | Zurückgegebenes Ergebnis |
| `ppt.generate` | Generierte Seite |
| `ppt.export` | Exportanfrage |
| `ppt.generate.status`, `ppt.generate.historical`, `ppt.export.status`, `ppt.delete` | Keine neue Gebühr |

Eine kostenlose Statusabfrage macht die zugrunde liegende Generierung oder den Export nicht kostenlos. Bei X können Paginierung und verschachtelte zurückgegebene Datensätze die abrechenbare Nutzung erhöhen.

## Guthaben und Reservierungen

Vor der Ausführung kann der Dienst genügend Guthaben für die Operation reservieren. Erfolgreiche Arbeit wird gegen diese Reservierung abgerechnet; bestätigte Fehler geben sie frei. Bei asynchronen Aufgaben bedeutet die Rückgabe einer ID nicht, dass die Abrechnung bereits endgültig ist.

Die Seitenpreis-Abrechnung von PPT reserviert bei der Erstellung zehn Seiten. Erfolgreiche Generierung rechnet die tatsächliche Ausgabe ab und gibt ungenutzte Mittel frei. Generierung und Export sind getrennte Gebühren. Siehe den [PPT-Workflow](https://openapi.felo.ai/de/docs/data-api/guides/felo-ppt.md) für das Verhalten bei wiederholtem Export.

Wenn Ausführung oder Abrechnung unklar sind, kann eine Reservierung ausstehen, während der Dienst sie abgleicht. Behandle nicht jedes Timeout oder 5xx als Beweis dafür, dass keine Arbeit stattgefunden hat oder dass eine wiederholte Anfrage kostenlos ist.

Prüfe dein verfügbares Guthaben und deine Nutzung in [Console Billing](https://openapi.felo.ai/console/billing). Hinweise zum Aufladen auf Kontoebene findest du unter [Billing and Credits](https://openapi.felo.ai/de/docs/faq/billing-and-credits.md).

## Wallet-Nutzung über die API abfragen

Kontoinhaber können Wallet-Aufrufprotokolle mit einem **Felo-Login-Token** einsehen. Diese Anmeldedaten unterscheiden sich vom API-Schlüssel, der für Data-API-Aufrufe verwendet wird; ersetze `FELO_API_KEY` nicht damit.

```bash
curl -sS 'https://openapi.felo.ai/api/wallet/usage?call_type=data' \
  -H 'Authorization: Bearer YOUR_FELO_LOGIN_TOKEN'
```

Datensätze befinden sich unter `data.items`; `call_type=data` filtert Funktionsaufrufe. Vergleiche die Nutzung mit den aktuellen Preisen des Kontos. Das Lesen von Datensätzen sendet keine weitere Generierungsaufgabe. Console Billing bleibt für Kontoprüfung und Aufladungen verfügbar.

## Fehler defensiv lesen

Prüfe zuerst den HTTP-Status. Fehler können eine der beiden folgenden Formen haben; die untenstehenden Werte sind illustrativ:

```json
{"error":{"code":"invalid_parameter","message":"Check the request fields"},"request_id":"example-request-id"}
```

```json
{"status":402,"code":"INSUFFICIENT_BALANCE","message":"Insufficient balance","request_id":"example-request-id"}
```

Lies `error.code` / `error.message`, wenn vorhanden, andernfalls `code` / `message`. Bewahre `request_id` auf, wenn sie zurückgegeben wird. Erfolgreiche Antworten variieren je nach Operation; zwinge sie nicht alle in denselben Fehler- oder `data`-Umschlag.

## Entscheide, was als Nächstes zu tun ist

| HTTP-Status | Häufige Ursache | Nächster Schritt |
|---|---|---|
| 400 | Fehlender oder ungültiger Parameter | Korrigiere die Anfrage vor einem erneuten Versuch |
| 401 | Fehlender, ungültiger, widerrufener oder abgelaufener Schlüssel | Prüfe den Schlüssel und den Authentifizierungs-Header |
| 402 | Unzureichendes Plattform-Guthaben | Prüfe verfügbares Guthaben und ausstehende Reservierungen; lade bei Bedarf auf |
| 404 | Ressource fehlt oder ist für dieses Konto nicht zugänglich | Prüfe die ID und das erstellende Konto |
| 409 | Operation kollidiert mit dem aktuellen Aufgabenstatus oder die Ausführung ist nicht bestätigt | Lies den Fehlercode und frage die vorhandene Aufgabe ab; dupliziere sie nicht sofort |
| 410 | Ressource abgelaufen oder gelöscht | Verwende eine gespeicherte Datei; erstelle nur bei Bedarf eine neue Aufgabe |
| 429 | Ratenlimit oder API-Key-Quota überschritten | Prüfe Rücksetzungsinformationen; drossele oder warte auf das Quota-Reset |
| 502 / 503 / 504 | Upstream-, Verfügbarkeits-, Timeout- oder Abrechnungsfehler | Prüfe, ob die Arbeit bereits existiert, bevor du eine bezahlte Operation erneut versuchst |

`execution_unconfirmed` (409) und `billing_settlement_pending` (503) erfordern besondere Sorgfalt: Reiche bezahlte Arbeit nicht sofort erneut ein. Frage bekannte Aufgaben ab oder kontaktiere den Support mit der Request-ID. Ein erfolgreicher HTTP-Status mit leerem Ergebnis ist etwas anderes als eine Fehlerantwort.

## Wiederholen, ohne doppelte Arbeit zu erzeugen

- Verwende für schreibgeschützte Aufgaben- und Exportstatus-Abfragen begrenztes Backoff und beachte `Retry-After`, wenn vorhanden.
- Frage bei einer fehlgeschlagenen Erstanfrage mit gespeichertem `task_id` diese Aufgabe ab, bevor du eine weitere erstellst.
- Wenn die Verbindung fehlgeschlagen ist, bevor du eine ID erhalten hast, kann das Ergebnis unbekannt sein. Gehe nicht davon aus, dass erneutes Senden die Anfrage deduplizieren wird.
- Unterscheide bei 429 zwischen einem kurzen Ratenlimit und einem API-Key-Quota-Fenster; wiederholte Versuche setzen das Quota nicht zurück.
- Beende Wiederholungen nach einer konfigurierten Frist und zeige dem Aufrufer einen umsetzbaren Fehler an.

Für Support stelle den Endpunkt, den ungefähren Zeitpunkt, den HTTP-Status und die Request-ID bereit. Gib niemals den vollständigen API-Schlüssel an.