Zum Hauptinhalt springen

Fehler-Antwortformat

Alle Fehler geben ein konsistentes JSON-Format mit optionalen Agent-First-Hinweisen zurück:
{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type",
    "code": "error_code",
    "param": "parameter_name",
    "did_you_mean": "suggested_model",
    "suggestions": [{"id": "model-id"}],
    "hint": "Next step guidance",
    "retryable": true,
    "retry_after": 30
  }
}
Die Basisfelder (message, type, code, param) sind immer vorhanden. Die Hinweisfelder (did_you_mean, suggestions, hint, retryable, retry_after, balance_usd, estimated_cost_usd) sind optionale Erweiterungen zur Selbstkorrektur von AI-Agenten. Siehe den Agent-First API-Leitfaden für Details. OpenAI-kompatible Endpunkte verwenden LemonData’s stabile Gateway-Fehlertypen. Anthropic-kompatible und Gemini-kompatible Endpunkte verwenden ihre eigenen nativen Fehlerfamilien und Antwortformate.

HTTP-Statuscodes

CodeBeschreibung
400Bad Request - Ungültige Parameter
401Unauthorized - Ungültiger oder fehlender API-Schlüssel
402Payment Required - Unzureichendes Guthaben
403Forbidden - Zugriff verweigert oder Modell nicht erlaubt
404Not Found - Modell oder Ressource nicht gefunden
413Payload Too Large - Eingabe- oder Dateigröße überschritten
429Too Many Requests - Ratenlimit überschritten
500Internal Server Error
502Bad Gateway - Fehler des Upstream-Providers
503Service Unavailable - Dienst vorübergehend nicht verfügbar
504Gateway Timeout - Anfrage hat zu lange gedauert

Fehlertypen

Authentifizierungsfehler (401)

TypCodeBeschreibung
invalid_api_keyinvalid_api_keyAPI-Schlüssel fehlt oder ist ungültig
expired_api_keyexpired_api_keyAPI-Schlüssel wurde widerrufen
from openai import OpenAI, AuthenticationError

try:
    response = client.chat.completions.create(...)
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")

Zahlungsfehler (402)

TypCodeBeschreibung
insufficient_balanceinsufficient_balanceKontostand ist zu niedrig (OpenAI-kompatible Endpunkte)
insufficient_balance_errorinsufficient_balanceKontostand ist zu niedrig (Anthropic-kompatible Endpunkte)
quota_exceededquota_exceededNutzungslimit des API-Schlüssels erreicht
from openai import OpenAI, APIStatusError

try:
    response = client.chat.completions.create(...)
except APIStatusError as e:
    if e.status_code == 402:
        print("Please top up your account balance")

Zugriffsfehler (403)

TypCodeBeschreibung
access_deniedaccess_deniedZugriff auf die Ressource verweigert
access_deniedmodel_not_allowedModell für diesen API-Schlüssel nicht erlaubt
{
  "error": {
    "message": "You don't have permission to access this model",
    "type": "access_denied",
    "code": "model_not_allowed"
  }
}

Validierungsfehler (400)

TypBeschreibung
invalid_request_errorAnfrageparameter sind ungültig
context_length_exceededEingabe ist zu lang für das Modell
model_not_foundAngefordertes Modell ist im aktuellen öffentlichen Vertrag nicht verfügbar
{
  "error": {
    "message": "Model not found: please check the model name",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-5.4",
    "suggestions": [{"id": "gpt-5.4"}, {"id": "gpt-5-mini"}],
    "hint": "Did you mean 'gpt-5.4'? Use GET https://api.lemondata.cc/v1/models to list all available models."
  }
}
Öffentliche Routen unterscheiden im Antwortkörper nicht zwischen Tippfehlern, versteckten, zurückgestellten oder nicht-öffentlichen Modellzuständen. Wenn ein Modell derzeit nicht über den öffentlichen Vertrag verfügbar ist, gibt LemonData model_not_found zurück.

Rate-Limit-Fehler (429)

Wenn Sie die Ratenbegrenzungen überschreiten:
{
  "error": {
    "message": "Rate limit: 60 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 60/min for user role."
  }
}
Enthaltene Header:
Retry-After: 8
Der Retry-After-Header und das Feld retry_after geben beide die exakte Anzahl an Sekunden an, die vor einem erneuten Versuch gewartet werden soll.

Payload zu groß (413)

Wenn Eingabe oder Dateigröße die Grenzwerte überschreitet:
{
  "error": {
    "message": "Input size exceeds maximum allowed",
    "type": "invalid_request_error",
    "code": "payload_too_large"
  }
}
Häufige Ursachen:
  • Bilddatei zu groß (max 20MB)
  • Audiodatei zu groß (max 25MB)
  • Eingabetext überschreitet die Kontextlänge des Modells

Upstream-Fehler (502, 503)

TypBeschreibung
upstream_errorProvider hat einen Fehler zurückgegeben
all_channels_failedKeine verfügbaren Provider
timeout_errorAnfrage ist zeitlich überschritten
Wenn alle Kanäle fehlschlagen, enthält die Antwort alternative Modelle:
{
  "error": {
    "message": "Model claude-opus-4-6 temporarily unavailable",
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-4-6", "status": "available", "tags": []},
      {"id": "gpt-5-mini", "status": "available", "tags": []}
    ],
    "hint": "Retry in 30s or switch to an available model."
  }
}

Fehlerbehandlung in Python

from openai import OpenAI, APIError, RateLimitError, APIConnectionError

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.lemondata.cc/v1"
)

def chat_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4o",
                messages=messages
            )
        except RateLimitError as e:
            if attempt < max_retries - 1:
                import time
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            raise
        except APIConnectionError as e:
            print(f"Connection error: {e}")
            raise
        except APIError as e:
            print(f"API error: {e.status_code} - {e.message}")
            raise

Fehlerbehandlung in JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.lemondata.cc/v1'
});

async function chatWithRetry(messages, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.chat.completions.create({
        model: 'gpt-4o',
        messages
      });
    } catch (error) {
      if (error instanceof OpenAI.RateLimitError) {
        if (attempt < maxRetries - 1) {
          await new Promise(r => setTimeout(r, 2 ** attempt * 1000));
          continue;
        }
      }
      throw error;
    }
  }
}

Beste Vorgehensweisen

Wenn Sie rate-limited sind, warten Sie bei erneuten Versuchen schrittweise länger:
wait_time = 2 ** attempt  # 1s, 2s, 4s, 8s...
Setzen Sie immer vernünftige Timeouts, um hängende Anfragen zu vermeiden:
client = OpenAI(timeout=60.0)  # 60 second timeout
Protokollieren Sie die vollständige Fehlerantwort inklusive Request-ID für den Support:
except APIError as e:
    logger.error(f"API Error: {e.status_code} - {e.message}")
Einige Modelle haben spezifische Anforderungen (z. B. maximale Tokens, Bildformate). Validieren Sie Eingaben, bevor Sie Anfragen stellen.