# OpenAPI-facturering en fouten

Begrijp platformsaldo, kosten voor verzoeken en resultaten, paginabepaling en veilige herhalingen.

Deze pagina is van toepassing op `/api/v1/data/*`, de platform-exclusieve API's van Felo OpenAPI. Aanroepen gebruiken **platformsaldo**, een USD-gedenomineerd servicecreditsaldo. Ze verbruiken geen Felo Pro-credits. De oudere [Felo API's](https://openapi.felo.ai/nl/docs/api-reference/felo-apis.md) onder `/v2` gebruiken Pro-credits.

## Lees huidige prijzen

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

Dit openbare eindpunt vereist geen sleutel. Match de vermeldingen op operatie-ID en lees het huidige tarief en de factureringseenheid; ga er niet van uit dat elke operatie hetzelfde kost en bevries geen tarief uit een voorbeeld in je toepassing.

| Operatie-ID | Factureringseenheid |
|---|---|
| `web.search`, `web.read`, `chat` | Verzoek |
| `x.user.info`, `x.user.search`, `x.user.tweets`, `x.tweet.search`, `x.tweet.replies` | Teruggegeven resultaat |
| `ppt.generate` | Gegenereerde pagina |
| `ppt.export` | Exportverzoek |
| `ppt.generate.status`, `ppt.generate.historical`, `ppt.export.status`, `ppt.delete` | Geen nieuwe kosten |

Een gratis statusquery maakt de onderliggende generatie of export niet gratis. Voor X kunnen paginering en geneste teruggegeven records het factureerbare gebruik verhogen.

## Saldo en reserveringen

Voor uitvoering kan de service voldoende saldo reserveren voor de bewerking. Geslaagd werk wordt verrekend tegen die reservering; bevestigde mislukking maakt die weer vrij. Voor asynchrone taken betekent het teruggeven van een ID niet dat de facturering al definitief is.

PPT-paginaprijs reserveert tien pagina's bij aanmaak. Succesvolle generatie rekent af op basis van de daadwerkelijke uitvoer en maakt ongebruikte middelen vrij. Generatie en export zijn afzonderlijke kosten. Zie de [PPT-workflow](https://openapi.felo.ai/nl/docs/data-api/guides/felo-ppt.md) voor gedrag bij herhaalde export.

Als uitvoering of verrekening onzeker is, kan een reservering in afwachting blijven terwijl de service deze afstemt. Behandel niet elke time-out of 5xx als bewijs dat er niets is gebeurd of dat een herhaald verzoek gratis is.

Bekijk je beschikbare saldo en gebruik in [Console Billing](https://openapi.felo.ai/console/billing). Zie [Facturering en credits](https://openapi.felo.ai/nl/docs/faq/billing-and-credits.md) voor top-up-begeleiding op accountniveau.

## Walletgebruik opvragen via de API

Accounteigenaren kunnen wallet-aanroeprecords inspecteren met een **Felo-inlogtoken**. Deze referentie verschilt van de API-sleutel die wordt gebruikt voor Data API-aanroepen; vervang `FELO_API_KEY` niet.

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

Records staan onder `data.items`; `call_type=data` filtert capability-aanroepen. Vergelijk gebruik met de huidige prijzen van het account. Het lezen van records dient geen nieuwe generatietaak in. Console Billing blijft beschikbaar voor accountcontrole en opwaarderingen.

## Lees fouten defensief

Controleer eerst de HTTP-status. Fouten kunnen een van deze vormen hebben; de onderstaande waarden zijn illustratief:

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

Lees `error.code` / `error.message` wanneer aanwezig, anders `code` / `message`. Behoud `request_id` wanneer deze wordt teruggegeven. Succesreacties verschillen per bewerking; forceer ze niet allemaal in dezelfde fout- of `data`-envelop.

## Bepaal wat je hierna doet

| HTTP-status | Veelvoorkomende oorzaak | Volgende stap |
|---|---|---|
| 400 | Ontbrekende of ongeldige parameter | Corrigeer het verzoek vóór het opnieuw proberen |
| 401 | Ontbrekende, ongeldige, ingetrokken of verlopen sleutel | Controleer de sleutel en authenticatieheader |
| 402 | Onvoldoende platformsaldo | Controleer beschikbaar saldo en openstaande reserveringen; vul indien nodig aan |
| 404 | Resource ontbreekt of is niet toegankelijk voor dit account | Controleer de ID en het aanmakende account |
| 409 | Bewerking botst met de huidige taakstatus, of uitvoering is onbevestigd | Lees de foutcode en query de bestaande taak; dupliceer deze niet meteen |
| 410 | Resource verlopen of verwijderd | Gebruik een opgeslagen bestand; maak alleen een nieuwe taak aan indien nodig |
| 429 | Snelheidslimiet of API-sleutelquotum overschreden | Inspecteer resetinformatie; vertraag of wacht op de quotumreset |
| 502 / 503 / 504 | Upstream, beschikbaarheid, time-out of verrekeningsfout | Controleer of werk al bestaat voordat je een betaalde bewerking opnieuw probeert |

`execution_unconfirmed` (409) en `billing_settlement_pending` (503) vereisen speciale zorg: dien betaald werk niet onmiddellijk opnieuw in. Query bekende taken of neem contact op met support met de request-ID. Een geslaagde HTTP-status met een lege reactie is iets anders dan een foutreactie.

## Herhaal zonder dubbel werk te maken

- Gebruik voor alleen-lezen taak- en exportstatusquery's begrensde backoff en respecteer `Retry-After` wanneer aanwezig.
- Voor een mislukte aanmaakverzoek met een opgeslagen `task_id`, query je die taak voordat je een andere aanmaakt.
- Als de verbinding uitviel voordat je een ID ontving, kan het resultaat onbekend zijn. Ga er niet van uit dat opnieuw verzenden het verzoek dedupliceert.
- Voor 429: onderscheid een korte snelheidslimiet van een API-sleutelquotumvenster; herhaaldelijk opnieuw proberen kan het quotum niet resetten.
- Stop herhalingen na een geconfigureerde deadline en toon een bruikbare fout aan de aanroeper.

Geef voor support het eindpunt, het tijdstip bij benadering, de HTTP-status en request-ID door. Neem nooit de volledige API-sleutel op.