Budgets je Schlüssel

Ein Budget begrenzt, was ein API-Schlüssel in Euro ausgeben darf. Ist es aufgebraucht, lehnt das Gateway weitere Anfragen dieses Schlüssels mit 402 ab. Andere Schlüssel Ihrer Organisation arbeiten weiter.

1. Einen Schlüssel je Anwendung erstellen

   Erstellen Sie für jede Anwendung und jede Umgebung einen eigenen Schlüssel, zum Beispiel chatbot-produktion und chatbot-test. So trifft ein Budget genau eine Anwendung, und der Verbrauch je Schlüssel zeigt, welche Anwendung welche Kosten verursacht.

   Admins Ihrer Organisation erstellen Schlüssel unter Models → API-Schlüssel mit Neuer Schlüssel.

   Ergebnis: Jede Anwendung hat einen eigenen Schlüssel.

2. Budget festlegen

   Tragen Sie beim Erstellen oder später über Details & Bearbeiten im Abschnitt Budget zwei Werte ein:

   • Ausgabenlimit (€): der Höchstbetrag, zum Beispiel 50 €. Leer bedeutet kein Limit.
   • Zurücksetzen: Nie, Täglich, Wöchentlich oder Monatlich.

   Zurücksetzen	Neuer Zeitraum beginnt
   Täglich	jeden Tag um 00:00 UTC
   Wöchentlich	montags um 00:00 UTC
   Monatlich	am 1. des Monats um 00:00 UTC
   Nie	nie; das Limit gilt für die gesamte Lebensdauer des Schlüssels

   Ergebnis: Unter Models → API-Schlüssel zeigt die Spalte Verbrauch den Stand im laufenden Zeitraum. Ist das Limit erreicht, steht dort Limit erreicht.

3. 402 behandeln

   Prüfen Sie bei Statuscode 402 das Feld code im Fehlerobjekt:

   • key_budget_exhausted: Das Budget dieses Schlüssels ist für den laufenden Zeitraum aufgebraucht.
   • insufficient_credit: Das Guthaben der Organisation reicht nicht. Diesen Fehler sehen Organisationen, die mit Guthaben abrechnen (siehe Guthaben & Abrechnung).

   Wiederholen Sie die Anfrage bei key_budget_exhausted nicht unverändert. Ist das Limit erreicht, scheitert sie bis zur nächsten Rücksetzung oder bis ein Admin das Limit erhöht. Nennt die Meldung eine Schätzung (siehe unten), kann ein kleineres max_tokens genügen.

   Ergebnis: Ihre Anwendung unterscheidet ein erschöpftes Budget von fehlendem Guthaben.

   curl Python TypeScript

   Shell

   curl -s https://api.noirdoc.de/v1/chat/completions \
     -H "Authorization: Bearer $NOIRDOC_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "qwen3.8-27b",
       "max_tokens": 500,
       "messages": [{"role": "user", "content": "Hallo"}]
     }' \
     | jq '.error.code'

   Python

   import os
   import openai
   from openai import OpenAI
   
   client = OpenAI(
       base_url="https://api.noirdoc.de/v1",
       api_key=os.environ["NOIRDOC_API_KEY"],
   )
   
   try:
       response = client.chat.completions.create(
           model="qwen3.8-27b",
           max_tokens=500,
           messages=[{"role": "user", "content": "Hallo"}],
       )
   except openai.APIStatusError as e:
       if e.status_code != 402:
           raise
       code = e.response.json()["error"]["code"]
       if code == "key_budget_exhausted":
           ...  # bis zur Rücksetzung pausieren
       elif code == "insufficient_credit":
           ...  # Admins zum Aufladen auffordern

   TypeScript

   import OpenAI from "openai";
   
   const client = new OpenAI({
     baseURL: "https://api.noirdoc.de/v1",
     apiKey: process.env.NOIRDOC_API_KEY,
   });
   
   try {
     await client.chat.completions.create({
       model: "qwen3.8-27b",
       max_tokens: 500,
       messages: [{ role: "user", content: "Hallo" }],
     });
   } catch (err) {
     if (!(err instanceof OpenAI.APIError)) throw err;
     if (err.status !== 402) throw err;
     if (err.code === "key_budget_exhausted") {
       // bis zur Rücksetzung pausieren
     } else if (err.code === "insufficient_credit") {
       // Admins zum Aufladen auffordern
     }
   }

Was das Budget zählt

Das Budget zählt Anfragen an von Noirdoc verwaltete Modelle mit Preis. Anfragen über Ihre eigenen Anbieter (BYOK) zählen nicht, denn deren Kosten rechnet Ihr Anbieter ab.

Das Gateway bucht die Kosten einer Anfrage nach der Antwort auf den Schlüssel.

Prüfung vor der Anfrage

{
  "error": {
    "type": "proxy_error",
    "code": "key_budget_exhausted",
    "message": "This request could cost up to 0.42 EUR, more …"
  }
}

Fehler