Fehler & Limits

Der Fehler-Envelope

Jeder Fehler hat eine stabile Form – und leakt niemals interne Mandanten-IDs oder Backend-Fehlertexte:

{
  "statusCode": 409,
  "code": "stale_source_version",
  "message": "Version 6 is older than the applied version 7.",
  "requestId": "req_...",
  "details": { }
}

Verzweige über code, nicht über message – Nachrichten können umformuliert werden, Codes sind stabil.

Request-IDs

Jede Response trägt X-Request-Id. Sende deine eigene (1–128 Zeichen; erstes Zeichen alphanumerisch, danach A-Za-z0-9._:-), um einen Request durch Conare-Edge und Memory-Plane zu korrelieren; andernfalls generiert Conare eine. Zitiere sie in jedem Support-Request.

Statuscodes

Status	Bedeutung	Was tun
`400`	Ungültiger Request (z. B. `model_not_served`, unbekannte Collection-ID)	Request korrigieren – die Nachricht sagt genau, was falsch ist
`401`	Fehlender oder ungültiger Key	Bearer-Token prüfen
`402`	Kontingent und Overage-Budget aufgebraucht	Response enthält Balance-/Reset-Metadaten – zeige sie an, retrye nicht blind
`403`	Key hat den benötigten Scope nicht	Scope der Integration gewähren
`409`	Versionskonflikt im Source-Lifecycle	Siehe source-owned memories – meist bedeutet das „bereits durabel”
`413`	Content zu groß	Payload aufteilen
`429`	Rate-limitiert	Gemäß Rate-Limit-Headern zurückschalten
`503`	Backend nicht bereit (z. B. `integration_unbillable`)	Mit Backoff retryen; `/api/v1/status` prüfen

Degradation statt Fehler

Wo ein günstigerer Fallback existiert, degradiert Conare, statt einen Fehler zu werfen:

Deep Recall bei aufgebrauchtem Legacy-Kontingent liefert { answer: null, results: [...], deepUsed: false } – du bekommst weiterhin gerankte rohe Memories.
Suggestions hat keinen sinnvollen Shallow-Fallback, daher ist ein aufgebrauchtes Kontingent ein hartes 402 (Legacy-Kontingentpläne: 429).
Fehlerhafte Modellausgabe bei Suggestions liefert { suggestions: [], raw: "<text>" } – behandle raw als anzeigbaren Fallback-Text.

Nie gezählt

Session-Ingest, save und Shallow-Search/-Recall werden auf keinem Plan gezählt. Kostenwarnungen feuern bei 75/90/100 %, und die Standardeinstellung ist ein hartes Stopp – keine bösen Überraschungen.

Erste Schritte

Grundlagen

Fehler & Limits

Der Fehler-Envelope

Request-IDs

Statuscodes

Degradation statt Fehler

Nie gezählt

​Der Fehler-Envelope

​Request-IDs

​Statuscodes

​Degradation statt Fehler

​Nie gezählt

Der Fehler-Envelope

Request-IDs

Statuscodes

Degradation statt Fehler

Nie gezählt