Production Guide

Empfehlungen für einen stabilen Live-Betrieb mit Timeouts, Retries, Idempotency, Streaming und sauberer Observability.

Secrets und Key-Hygiene

Behandeln Sie API-Keys wie Produktions-Credentials und trennen Sie Entwicklung, Staging und Production sauber.

  • Speichern Sie Keys ausschließlich in Server-Umgebungsvariablen oder Secret-Managern.
  • Nutzen Sie getrennte Keys für Development, Staging und Production.
  • Rotieren Sie produktive Keys regelmäßig und dokumentieren Sie den Besitzer jedes Keys.
  • Deaktivieren oder löschen Sie ungenutzte Keys sofort.
Timeouts und Abbruchlogik

Setzen Sie pro Request einen klaren Client-Timeout und behandeln Sie Abbrüche explizit. Für interaktive Flows sind 20 bis 30 Sekunden ein guter Startwert; längere Batch-Jobs sollten separat orchestriert werden.

request.tstypescript
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);

try {
  const response = await fetch("https://api.vantero.chat/v1/chat/completions", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.VANTERO_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      model: "gpt-5-mini",
      messages: [{ role: "user", content: "Summarize this report." }],
    }),
    signal: controller.signal,
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }
} finally {
  clearTimeout(timeout);
}
Retries mit Backoff

Retries sollten gezielt auf temporäre Fehler begrenzt werden, nicht auf beliebige 4xx-Antworten.

  • Retrybar sind in der Regel Netzwerkfehler, Timeouts, 429 sowie 500/503.
  • Nicht retrybar sind in der Regel 400, 401 und 404 ohne vorherige Korrektur.
  • Verwenden Sie Exponential Backoff mit Jitter statt festen Sleep-Intervallen.
  • Begrenzen Sie die Anzahl der Retries und loggen Sie jeden finalen Fehler mit Request-ID.
Idempotency und Request-Nachverfolgung

Für wiederholbare POST-Requests sollten Sie einen stabilen Idempotency-Key setzen und den serverseitigen Request-Trace mitloggen.

headers.httphttp
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: req_9f84f48a...   # optional, recommended for POST retries
X-End-User-Id: crm-user-42         # optional
X-Project-Id: app-backend          # optional

# response
X-Request-Id: 2fbd62fe-...         # always persist in your logs
  • Generieren Sie für jeden schreibenden oder wiederholbaren Request einen eindeutigen Idempotency-Key.
  • Verwenden Sie bei einem Retry denselben Idempotency-Key erneut, nicht einen neuen.
  • Persistieren Sie die zurückgegebene X-Request-Id in Ihren Logs, damit Support-Fälle schnell nachvollziehbar bleiben.
Streaming robust konsumieren

Behandeln Sie Streaming als SSE-Lifecycle und nicht als einen normalen JSON-Response.

streaming-checklist.txttext
1. Start the request with stream: true.
2. Read SSE events incrementally instead of buffering the whole body.
3. Treat [DONE] as the terminal marker.
4. Only persist usage after the final chunk when include_usage is enabled.
5. If the stream breaks, retry only when your request is idempotent.
  • Lesen Sie Events inkrementell statt auf den kompletten Response-Body zu warten.
  • Behandeln Sie [DONE] als sauberen Abschluss des Streams.
  • Usage-Daten stehen erst im finalen Chunk zur Verfügung, wenn include_usage aktiviert ist.
  • Wenn ein Stream abbricht, retrien Sie nur idempotente Requests und protokollieren Sie den Abbruch klar.
Go-live Checkliste

Diese Punkte sollten vor dem Rollout in Production abgehakt sein.

  • Client-Timeouts und Abbruchpfade sind implementiert und getestet.
  • Retry-Logik verwendet Backoff und retried nur temporäre Fehler.
  • Request-IDs, Modell, Latenz und Statuscodes landen strukturiert im Logging.
  • API-Key-Rotation und Environment-Trennung sind dokumentiert.
  • Streaming-Clients behandeln Deltas, finale Usage und [DONE] korrekt.