Fehlerbehebung

Die meisten Probleme zeigen sich als HTTP-Status und code im Fehler-Body. Suchen Sie unten den Code; Fehler enthält die vollständige Liste. Fehlgeschlagene Anfragen (jedes 4xx oder 5xx) werden nie berechnet.

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

401 invalid_api_key

Der Schlüssel fehlt, ist fehlerhaft oder wurde widerrufen.

• Senden Sie ihn als Authorization: Bearer sk-api14-.... Die OpenAI-SDKs tun das aus apiKey / api_key; prüfen Sie bei curl, dass $API14_API_KEY in der Shell, aus der Sie starten, tatsächlich gesetzt ist (echo ${API14_API_KEY:0:9} sollte sk-api14- ausgeben).
• Achten Sie auf überflüssige Anführungszeichen oder Zeilenumbrüche, wenn der Schlüssel aus einer .env-Datei kommt.
• Ein in der Umgebung verbliebener OPENAI_API_KEY kann den beabsichtigten Schlüssel überschreiben. Übergeben Sie den Schlüssel explizit, um das auszuschließen.
• Ein widerrufener Schlüssel schlägt sofort fehl. Schlüssel werden nur einmal angezeigt; haben Sie einen verloren, erstellen Sie unter API-Schlüssel einen neuen und widerrufen Sie den alten.

Siehe Authentifizierung.

402 insufficient_balance

Ihr USD-Guthaben beträgt 0 $ oder (bei Video) liegt unter den geschätzten Kosten des Auftrags. Anfragen bleiben blockiert, bis Sie Guthaben aufladen; Wiederholen hilft nicht.

• Prüfen Sie das Guthaben mit GET /credits oder unter Abrechnung. Siehe Guthaben und Schlüsselinfo.
• Laden Sie Guthaben auf oder aktivieren Sie die automatische Aufladung. Pläne fügen jeden Monat enthaltene Nutzung zum selben Guthaben hinzu. Siehe Preise & Abrechnung.
• Behandeln Sie diesen Code in lang laufenden Jobs als fatal und stoppen Sie, statt die Wiederholungen des SDK weiterlaufen zu lassen.

403 model_not_allowed oder plan_required

• model_not_allowed: Der Schlüssel hat eine Modell-Allowlist, die diese Modell-ID nicht enthält. Bearbeiten Sie die Allowlist des Schlüssels unter API-Schlüssel oder verwenden Sie einen Schlüssel ohne Allowlist. Variantensuffixe zählen: Prüfen Sie, dass die exakt gesendete ID erlaubt ist.
• plan_required: Ihr Plan enthält diese Modellkategorie nicht. Die Standardpläne umfassen alle Kategorien; prüfen Sie Ihren Plan auf der Preisseite.

404 model_not_found oder not_found

• model_not_found: Die Modell-ID ist unbekannt, deaktiviert oder entfernt. IDs enthalten das Provider-Präfix: openai/gpt-5-mini, nicht gpt-5-mini. Die exakte ID finden Sie mit GET /models oder GET /models/{id} (kein Schlüssel nötig). Siehe Modell-IDs & Varianten.
• not_found: Der Pfad existiert nicht, oder der Videoauftrag bzw. die Generation-ID gehört nicht Ihnen. Das bedeutet meist eine falsche Base URL (siehe unten). Auch ein Generation-Abruf direkt nach einer Anfrage kann einige Sekunden lang 404 liefern, bis der Datensatz erscheint.

Falsche Base URL

Die Base URL lautet genau:

https://api14.com/api/v1

Häufige Fehler:

Eigenheiten einzelner Bibliotheken: ruby-openai fügt v1 selbst hinzu, daher ist sein uri_base https://api14.com/api (Ruby); openai-go erwartet einen abschließenden Schrägstrich, https://api14.com/api/v1/ (Go).

429 rate_limited

Sie haben das Limit für Anfragen pro Minute Ihres Schlüssels oder Plans überschritten (Free 5, Pro 100, Team 3.000, Enterprise 3.000+). Die Antwort enthält Retry-After: 60.

• Warten Sie Retry-After ab und wiederholen Sie mit exponentiellem Backoff und Jitter. Die offiziellen OpenAI-SDKs tun das bereits (standardmäßig zwei Wiederholungen; erhöhen Sie maxRetries / max_retries).
• Takten Sie bei Massenarbeit die Anfragen, statt alle auf einmal abzufeuern, und packen Sie mehrere Elemente in eine Anfrage. Siehe Anleitung: Batch-Verarbeitung.
• Ein 429 kann auch vom Upstream-Provider kommen, besonders bei :free-Varianten. Nutzen Sie Modell-Fallbacks oder Provider-Routing, um die Last zu verteilen.

429 daily_limit_reached

Der Schlüssel hat sein tägliches USD-Ausgabenlimit erreicht. Wiederholen hilft bis zum nächsten UTC-Tag nicht. Erhöhen oder entfernen Sie das Limit unter API-Schlüssel, wenn der Datenverkehr erwartet ist. Stellen Sie sicher, dass Ihre Wiederholungslogik diesen Code von rate_limited unterscheidet, sonst wiederholen Jobs ohne Nutzen weiter. Siehe Rate Limits.

Timeouts

Große Modelle, Reasoning-Modelle und lange Ausgaben können Minuten dauern.

• Prüfen Sie das Timeout Ihres Clients. Die SDKs für Node und Python haben standardmäßig 10 Minuten; andere HTTP-Clients verwenden oft kürzere Standardwerte.
• Streamen Sie lange Generierungen. Tokens treffen schon nach Sekunden ein, und Timeouts für inaktive Verbindungen in Proxys und Load Balancern sind kein Problem mehr. Siehe Streaming.
• Setzen Sie max_tokens und bei Reasoning-Modellen einen niedrigeren Reasoning-Aufwand.
• Wenn Sie Anfragen über Ihren eigenen Server weiterleiten, gelten auch dessen Proxy-Timeouts (zum Beispiel nginx proxy_read_timeout, standardmäßig 60 Sekunden).
• Ein Timeout auf Ihrer Seite bricht die Upstream-Generierung nicht ab; sie kann dennoch berechnet werden. Prüfen Sie dies mit Generation abrufen anhand der Anfrage-ID.

Streaming bricht ab oder endet früh

• Prüfen Sie finish_reason im letzten Chunk. "length" bedeutet, dass max_tokens erreicht wurde; "error" bedeutet, dass der Provider mitten im Stream ausgefallen ist, und der Chunk enthält ein error-Objekt. Wiederholen Sie oder fügen Sie Fallbacks hinzu.
• Proxys und Serverless-Plattformen puffern oder kappen SSE-Antworten manchmal. Deaktivieren Sie das Puffern (X-Accel-Buffering: no bei nginx) und prüfen Sie die maximale Antwortdauer der Plattform.
• Wenn Sie den Stream selbst parsen, ignorieren Sie Kommentarzeilen, die mit : beginnen (Keep-Alives), und stoppen Sie bei data: [DONE].
• Ein vorzeitiges Schließen der Verbindung storniert die Berechnung nicht: Der Provider kann die Generierung trotzdem beenden.

CORS-Fehler und Browser-Apps

Legen Sie niemals einen API-Schlüssel in Browser- oder Mobilcode. Jeder kann ihn aus der Seite auslesen und Ihr Guthaben ausgeben. Rufen Sie api14 von Ihrem eigenen Backend auf und stellen Sie dem Browser nur Ihren eigenen Endpunkt bereit:

// 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, // diese Eingabe validieren und begrenzen
    stream: true,
  });
  for await (const chunk of stream) res.write(chunk.choices[0]?.delta?.content ?? "");
  res.end();
});

Ein CORS-Fehler im Browser während der Entwicklung liegt meist an einer falschen Base URL (die Anfrage erreichte die Website statt der API) oder an einem benutzerdefinierten Request-Header, den der Preflight der API nicht erlaubt; beides löst die Verlagerung des Aufrufs auf Ihren Server.

Probleme mit SDK-Versionen

• Python openai unter 1.0 verwendet openai.ChatCompletion.create und openai.api_base. Aktualisieren Sie mit pip install -U openai und nutzen Sie den Client OpenAI(base_url=..., api_key=...).
• chat.completions.parse fehlt: Ältere 1.x/4.x-Versionen haben nur client.beta.chat.completions.parse. Aktualisieren Sie das Paket.
• Fehler "unbekannter Parameter" vom SDK bei Gateway-Feldern (provider, models, reasoning, plugins): Übergeben Sie sie in Python mit extra_body oder der entsprechenden Extra-Body-Option anderer SDKs. Siehe OpenAI-SDK-Kompatibilität.
• Upstream-400 mit einer Provider-Meldung: Der Parameter wird von diesem Modell oder Provider nicht unterstützt. Prüfen Sie supported_parameters des Modells unter Modelle oder fügen Sie provider: { "require_parameters": true } hinzu.