[SYNDERESIS / API](/de/dokumentation/) BETRIEB


Gehostete API für Kunden · Vertrag geprüft am 7. November 2026



# Integration in den Produktivbetrieb


Auf dieser Seite- [Integration in den Produktivbetrieb](#production-integration)- [Fehler und Abhilfen](#errors-and-remedies)

- [Wiederholungen und ungewisse Ergebnisse](#retries-and-uncertain-outcomes)

- [Timeouts und Nebenläufigkeit](#timeouts-and-concurrency)

- [Überwachung](#monitoring)

- [Validierung vor dem Start](#validate-before-launch)

- [Kontakt und Fehlerbehebung](#contact-and-troubleshooting)


Bauen Sie um explizite Zeit-, Kosten- und Fehlerbudgets herum. Die Beispiele sind ein Ausgangspunkt; Ihre Anwendung trägt die Verantwortung für die Authentifizierung der Endnutzer, die Nebenläufigkeit, externe Aktionen und ihre eigenen Servicezusagen.



## Fehler und Abhilfen


Fehler der nativen API haben diese Form:



```
{
  "error": {
    "type": "unauthorized",
    "code": "unauthorized",
    "message": "Missing API key.",
    "request_id": "example-request-id"
  }
}
```


Die veranschaulichende Meldung ist gekürzt. type und code verwenden denselben Maschinencode; message gibt eine Anleitung für Menschen. Verzweigen Sie anhand von status und code, statt den Text von message abzugleichen. Bewahren Sie die request_id für den Support auf. Interne Anbieter und Stacktraces sollten zur Wiederherstellung nicht erforderlich sein.


| HTTP und Code | Bedeutung | Aktion |



| 400 invalid_request | Ungültiges JSON/Objekt, fehlende/falsche Felder, ungültiges Transkript oder ein Request-Body über dem Endpunktlimit. | Korrigieren Sie die Anfrage. Limit für Answers: 65536 Bytes; 921600 Bytes für chat completions. |

| 400 unsupported_model | Der Alias wird auf diesem Pfad nicht akzeptiert, zum Beispiel labora mit tools. | Verwenden Sie die Modellerkennung und die Dispatch-Tabelle. synderesis-pro wird als dieselbe Auswahl wie pro akzeptiert. |

| 400 unsupported_parameter | Bei chat completions wurde die automatische Auswahl mit tools oder Tool-Ergebnissen kombiniert, oder auf dem Antwortpfad wurde stream=true gesendet. | Wählen Sie ein explizites Modell für den Tool-Pfad oder entfernen Sie stream. POST /v1/answers ignoriert stream und tools. |

| 401 unauthorized | Fehlende, ungültige, abgelaufene/widerrufene oder widersprüchliche Anmeldedaten. | Korrigieren Sie die Konfiguration der Anmeldedaten. |

| 402 free_allocation_exhausted | Die einmalige anfängliche Token-Zuteilung ist ausgeschöpft. | Abonnieren Sie über Konto oder bestätigen Sie die zutreffende Berechtigung. |

| 402 insufficient_credit | Abrechenbare Arbeit auf dem Antwortpfad kann nicht genug Kontoguthaben reservieren. | Fügen Sie Guthaben über Konto hinzu und prüfen Sie Ihre Berechtigung bzw. Ihren Tarif. |

| 402 inference_quota_exhausted | Ein gemeinsam genutzter Schlüssel nur für Inferenz kann die Anfrage unter seiner Obergrenze für die Lebensdauer nicht zulassen. | Verwenden Sie diesen Schlüssel nicht mehr; er wird nicht aufgefüllt. |

| 403 inference_scope_denied | Ein gemeinsam genutzter Schlüssel nur für Inferenz hat eine Route außerhalb seines Geltungsbereichs aufgerufen. | Verwenden Sie ihn nur für Antworten, chat completions und die Modellerkennung. |

| 403 origin_invalid / csrf_invalid | Die Kontrolle der Browser-Sitzungsherkunft/CSRF ist fehlgeschlagen. | Verwenden Sie den unterstützten Browser-Ablauf. Aufrufe mit einem Serverschlüssel sollten keine Browser-Sitzung mitführen. |

| 404 not_found | Unbekannter Pfad oder nicht verfügbare referenzierte Ressource. | Prüfen Sie die genaue URL und die API-Basis. |

| 405 method_not_allowed | Der Pfad unterstützt diese Methode nicht. | Verwenden Sie die dokumentierte Methode; prüfen Sie Allow. OPTIONS-Anfragen des Browsers werden nicht unterstützt. |

| 429 quota_exceeded | Ein Kontingent für Konto/Plan wurde erreicht. | Prüfen Sie Zuteilung/Plan/Zurücksetzen; wiederholte sofortige Versuche beheben es nicht. |

| 429 rate_limited | Ein routenspezifischer Begrenzer hat die Anfrage abgelehnt. | Warten Sie und versuchen Sie es dann im Rahmen einer begrenzten Richtlinie erneut. |

| 503 service_unavailable | Eine Abhängigkeit, ein Kontingent-Unterpfad oder ein Generierungsvorgang konnte nicht abgeschlossen werden. | Prüfen Sie den Health-Status, verwenden Sie eine vorsichtige, begrenzte Wiederherstellung und bewahren Sie die Request-ID auf. |

| 500 internal_error | Ein nicht abgefangener Fehler an einer nativen Grenze. | Bewahren Sie die Request-ID auf; behandeln Sie das Ergebnis als ungewiss und wenden Sie sich an den Support, wenn es anhält. |


Einige Fehler bei der Laufzeitinitialisierung und an Grenzen können vor der normalen Anfrageverarbeitung auftreten. Eine unerwartete Antwort kann aufgrund von Infrastruktur außerhalb der Anwendung kein JSON sein; behandeln Sie sie, ohne ihren Body Endnutzern offenzulegen.



## Wiederholungen und ungewisse Ergebnisse


Wiederholen Sie Antworten zu Validierung, Authentifizierung, nicht unterstütztem Modell oder erschöpfter Zuteilung nicht automatisch. Kontingentfehler erfordern eine Abhilfe durch Plan oder Zurücksetzen.


Verwenden Sie bei einer schreibgeschützten Modell- oder Lookup-Anfrage, bei der Ihre Anwendung mögliche doppelte Berechnung und Verbrauchserfassung akzeptiert, ein kleines Wiederholungsbudget für vorübergehende Fehler. Eine angemessene Client-Richtlinie ist ein erster Versuch plus höchstens zwei Wiederholungen, eine exponentielle Verzögerung ab 0.5 Sekunden, zufälliger Jitter und eine Gesamtfrist. Dies ist eine **Leitlinie für die Anwendung**, kein SDK- oder Server-Standard von Synderesis.


Beachten Sie Retry-After, wenn vorhanden, verlassen Sie sich aber nicht darauf. Beenden Sie den Vorgang, wenn ein Fehler auf erschöpfte Kapazität, eine dauerhaft ungültige Anfrage oder eine unbekannte folgenreiche Aktion hinweist.


Idempotency-Key dient als Identität für Abrechnung oder Reservierung auf Generierungspfaden. Er ist keine dokumentierte Garantie für eine Generierung genau einmal und keine API zur Wiedergabe zwischengespeicherter Antworten. Eine Wiederverwendung kann auf einen abgeschlossenen oder nicht übereinstimmenden Reservierungszustand treffen. Leiten Sie aus seinem Vorhandensein keine sichere automatische Neugenerierung ab.


Ein Timeout oder ein Zurücksetzen der Verbindung belegt nicht, dass der Server keine Arbeit ausgeführt hat. Gleichen Sie Nutzung und Request-IDs ab und verwenden Sie ein separates dauerhaftes Aktionsregister, um die Wiederholung der Auswirkungen externer Tools zu vermeiden. Prüfen Sie das Wiederholungsverhalten jedes Drittanbieter-SDK und konfigurieren Sie es ausdrücklich.



## Timeouts und Nebenläufigkeit


Legen Sie Verbindungs-, Lese- und Gesamt-Timeouts in Ihrem Client und im Reverse-Proxy fest. Der Handler für Transkript und Tools erlaubt einen längeren Vorgang upstream als der Handler für kurze Antworten; gepuffertes SSE beseitigt die Wartezeit der Generierung nicht.


Beginnen Sie mit geringer Nebenläufigkeit und bescheidenen Obergrenzen für die Ausgabe. Erhöhen Sie diese erst, nachdem Sie Latenz, Kontingent und das Verhalten des Guthabens für Ihr Konto beobachtet haben. Der geprüfte öffentliche Vertrag legt weder eine universelle Nebenläufigkeit noch einen garantierten Latenzwert fest.


Leiten Sie den Abbruch des Clients zur Ressourcenhygiene weiter und bewahren Sie dabei einen Zustand mit ungewissem Ergebnis. Ein Abbruch garantiert weder einen Abbruch upstream noch eine Erstattung.



## Überwachung


Erfassen Sie:


- Request-ID und Ihre eigene Korrelations-ID der Anwendung.

- Endpunkt und öffentlicher Modellalias.

- Status- oder Fehlercode, Latenz und Versuchsnummer.

- Zurückgegebene Token-Nutzung sowie Trends von Guthaben und Zuteilung auf Kontoebene.

- Anzahl der Runden der Tool-Schleife und unabhängig erfasste Aktionsergebnisse.


Verwenden Sie Alarme bei anhaltenden Fehlern, unerwartetem Nutzungswachstum und bei Erschöpfung von Kontingent oder Guthaben. Vermeiden Sie die Protokollierung von Prompts oder Schlüsseln. GET /health meldet die Bereitschaft und GET /v1/usage den Kontozustand; keines von beiden ist ein vollständiges Produktions-SLA.



## Vor dem Start validieren


Bestätigen Sie den genauen Modellalias und den Verarbeitungspfad, die Konversationssemantik, die Grenzen für Body und Ausgabe sowie etwaige Funktionsberechtigungen. Prüfen Sie Ihren Parser mit erfolgreichen Antworten, leeren Quellenlisten, nullbaren Inhalten von Tool-Aufrufen, Abschlüssen wegen Länge, unbekannten optionalen Feldern, Fehler-JSON und unvollständigen Streams.


Testen Sie die Erschöpfung von Konto oder Guthaben in einem geeigneten kontrollierten Aufbau. Gleichen Sie eine begrenzte Stichprobe der tatsächlichen Kontonutzung mit Ihrem vereinbarten Tarif ab. Legen Sie die Bedingungen für Verarbeiter und Aufbewahrung sowie den Supportweg fest.


Halten Sie ein Rollback der Anwendung bereit, das Aufrufe deaktivieren oder auf eine gesondert qualifizierte Konfiguration wechseln kann, ohne den Benutzerkontext stillschweigend zu verwerfen oder folgenreiche Aktionen zu wiederholen.



## Kontakt und Fehlerbehebung


Verwenden Sie [hello@synderesis.eu](mailto:hello@synderesis.eu) mit der UTC-Zeit, dem Endpunkt, dem HTTP-Status, dem öffentlichen Modellalias und der Request-ID. Fügen Sie bei Bedarf eine geschwärzte minimale Anfrage bei. Fügen Sie niemals einen echten API-Schlüssel, ein Cookie, privaten Quellentext oder ungeschwärzte Benutzerdaten bei.


Die geprüfte Dokumentation legt keine öffentliche Statusseiten-URL, keine Zusage zum Servicelevel, keine garantierte Antwortzeit des Supports und keine Vereinbarung über automatisches Failover fest.


[Übersicht](/de/dokumentation/)[API-Referenz →](/de/dokumentation/referenz/)


[Diese Anleitung als Markdown lesen](/de/docs/production.md)
