Probleemoplossing

De meeste problemen tonen zich als een HTTP-status en een code in de foutbody. Zoek de code hieronder op; Fouten bevat de volledige lijst. Mislukte requests (elke 4xx of 5xx) worden nooit in rekening gebracht.

{ "error": { "message": "...", "type": "authentication_error", "code": "invalid_api_key" } }

401 invalid_api_key

De key ontbreekt, is ongeldig opgemaakt of is ingetrokken.

• Stuur hem mee als Authorization: Bearer sk-api14-.... De OpenAI-SDK's doen dit op basis van apiKey / api_key; controleer bij curl of $API14_API_KEY echt is ingesteld in de shell waarin je het uitvoert (echo ${API14_API_KEY:0:9} hoort sk-api14- te tonen).
• Let op losse aanhalingstekens of regeleinden wanneer de key uit een .env-bestand komt.
• Een OPENAI_API_KEY die in de omgeving is achtergebleven, kan de key overschrijven die je wilde gebruiken. Geef de key expliciet mee om dit uit te sluiten.
• Een ingetrokken key faalt direct. Keys worden maar één keer getoond, dus als je er een kwijt bent, maak je in API-keys een nieuwe aan en trek je de oude in.

Zie Authenticatie.

402 insufficient_balance

Je USD-saldo is $0, of (bij video) lager dan de geschatte kosten van de taak. Requests blijven geblokkeerd totdat je saldo toevoegt; opnieuw proberen helpt niet.

• Controleer het saldo met GET /credits of in Facturering. Zie Saldo en key-info.
• Voeg saldo toe of schakel automatisch opwaarderen in. Abonnementen voegen elke maand inbegrepen gebruik toe aan hetzelfde saldo. Zie Prijzen en facturering.
• Behandel deze code in langlopende taken als fataal en stop, in plaats van de nieuwe pogingen van de SDK te laten doordraaien.

403 model_not_allowed of plan_required

• model_not_allowed: de key heeft een modelallowlist die dit model-id niet bevat. Pas de allowlist van de key aan in API-keys, of gebruik een key zonder allowlist. Variantachtervoegsels tellen mee: controleer of het exacte id dat je verstuurt is toegestaan.
• plan_required: je abonnement bevat deze modelcategorie niet. De standaardabonnementen dekken alle categorieën; controleer je abonnement op de prijzenpagina.

404 model_not_found of not_found

• model_not_found: het model-id is onbekend, uitgeschakeld of verwijderd. Id's bevatten het providervoorvoegsel: openai/gpt-5-mini, niet gpt-5-mini. Zoek het exacte id op met GET /models of GET /models/{id} (geen key nodig). Zie Model-id's en varianten.
• not_found: het pad bestaat niet, of de videotaak of het generation-id is niet van jou. Dit wijst meestal op een verkeerde base URL (zie hieronder). Een Generatie opzoeken direct na een request kan ook enkele seconden 404 geven totdat het record verschijnt.

Verkeerde base URL

De base URL is precies:

https://api14.com/api/v1

Veelgemaakte fouten:

Eigenaardigheden van bibliotheken: ruby-openai voegt zelf v1 toe, dus de uri_base is https://api14.com/api (Ruby); openai-go verwacht een afsluitende schuine streep, https://api14.com/api/v1/ (Go).

429 rate_limited

Je hebt de limiet voor requests per minuut van je key of abonnement overschreden (Free 5, Pro 100, Team 3000, Enterprise 3000+). De response bevat Retry-After: 60.

• Wacht op Retry-After en probeer opnieuw met exponentiële backoff en jitter. De officiële OpenAI-SDK's doen dit al (standaard twee nieuwe pogingen; verhoog maxRetries / max_retries).
• Pace requests bij bulkwerk in plaats van ze allemaal tegelijk af te vuren, en zet meerdere items in één request. Zie Gids: batchverwerking.
• Een 429 kan ook van de upstream-provider komen, vooral bij :free-varianten. Gebruik model-fallbacks of provider routing om de belasting te spreiden.

429 daily_limit_reached

De key heeft zijn dagelijkse USD-bestedingslimiet bereikt. Opnieuw proberen helpt niet tot de volgende UTC-dag. Verhoog of verwijder de limiet in API-keys als het verkeer verwacht is. Zorg dat je logica voor nieuwe pogingen deze code onderscheidt van rate_limited, anders blijven taken voor niets opnieuw proberen. Zie Rate limits.

Timeouts

Grote modellen, reasoning-modellen en lange uitvoer kunnen minuten duren.

• Controleer de timeout van je client. De Node- en Python-SDK's hebben standaard 10 minuten; andere HTTP-clients gebruiken vaak kortere standaardwaarden.
• Stream lange generaties. Tokens beginnen binnen enkele seconden binnen te komen en timeouts voor inactieve verbindingen in proxy's en load balancers zijn dan geen probleem meer. Zie Streaming.
• Stel max_tokens in en, voor reasoning-modellen, een lagere reasoning-inspanning.
• Als je requests via je eigen server doorstuurt, gelden ook de proxytimeouts daarvan (bijvoorbeeld nginx proxy_read_timeout, standaard 60 seconden).
• Een timeout aan jouw kant annuleert de upstream-generatie niet, die mogelijk nog wordt gefactureerd. Gebruik Generatie opzoeken met het request-id om dit te controleren.

Streaming valt weg of stopt vroegtijdig

• Controleer finish_reason op de laatste chunk. "length" betekent dat max_tokens is bereikt; "error" betekent dat de provider halverwege de stream faalde, en de chunk bevat een error-object. Probeer opnieuw, of voeg fallbacks toe.
• Proxy's en serverless-platforms bufferen of onderbreken SSE-responses soms. Schakel buffering uit (X-Accel-Buffering: no op nginx) en controleer de maximale responsduur van het platform.
• Als je de stream zelf parset, negeer dan commentaarregels die met : beginnen (keep-alives) en stop bij data: [DONE].
• De verbinding vroegtijdig sluiten annuleert de rekening niet: de provider kan de generatie toch afmaken.

CORS-fouten en browserapps

Zet nooit een API-key in browser- of mobiele code. Iedereen kan hem uit de pagina lezen en je saldo uitgeven. Roep api14 aan vanuit je eigen backend en stel alleen je eigen endpoint beschikbaar aan de browser:

// server.js (Node / Express)
app.post("/api/chat", async (req, res) => {
  const stream = await client.chat.completions.create({
    model: "openai/gpt-5-mini",
    messages: req.body.messages, // valideer en begrens deze invoer
    stream: true,
  });
  for await (const chunk of stream) res.write(chunk.choices[0]?.delta?.content ?? "");
  res.end();
});

Een CORS-fout in de browser tijdens de ontwikkeling komt meestal door een verkeerde base URL (het request kwam op de website in plaats van de API terecht) of een eigen requestheader die de preflight van de API niet toestaat; de aanroep naar je server verplaatsen lost beide op.

Problemen met SDK-versies

• Python openai lager dan 1.0 gebruikt openai.ChatCompletion.create en openai.api_base. Upgrade met pip install -U openai en gebruik de client OpenAI(base_url=..., api_key=...).
• chat.completions.parse ontbreekt: oudere 1.x-/4.x-releases hebben alleen client.beta.chat.completions.parse. Upgrade het pakket.
• Fouten over onbekende parameters van de SDK voor gateway-velden (provider, models, reasoning, plugins): geef ze mee met extra_body in Python, of de equivalente extra-body-optie in andere SDK's. Zie Compatibiliteit met de OpenAI-SDK.
• Upstream 400 met een melding van de provider: de parameter wordt niet ondersteund door dat model of die provider. Controleer de supported_parameters van het model in Modellen, of voeg provider: { "require_parameters": true } toe.