Fehlerkatalog
Hier steht jeder Fehler, dem ein Agent bei der FrankKi-Partner-Schnittstelle begegnen kann: seine Bedeutung, was du als Nächstes tust, und ob die Antwort einen fixUrl-Link mitliefert. Ein fixUrl ist ein Deep-Link in das authentifizierte Web-Dashboard, direkt auf den Bildschirm, der die Ursache behebt, zum Beispiel das Absenderprofil oder die Wallet-Aufladung. Dieser Zusammenhang gilt für jeden Code in der Tabelle und wird hier nur einmal erklärt, kein Code weiter unten wiederholt ihn. Du musst für keinen dieser Fehler Backend-Quellcode lesen oder ein Ticket eröffnen.
Bedeutung und Recovery-Klasse für die Codes mit der Quelle "transport" (Token-, Schema- und Transport-Ebene) werden hier von Hand gepflegt statt aus errors.json generiert, weil sie keinen Gate-Eintrag im Backend haben. Ändert sich das, übernimmt errors.json automatisch den Vorrang.
Diese drei Codes gehören zum weltweiten Versand (siehe PingenInternational) und werden dort abschließend definiert. Diese Tabelle referenziert nur ihre Bedeutung, sie definiert sie nicht neu.
| Code | HTTP | Bedeutung | Recovery | Korrektur-Link |
|---|---|---|---|---|
ADDRESS_INVALID | 422 | Die Empfängeradresse ist unvollständig oder ungültig. Bitte prüfe deine Angaben. EN: The recipient address is incomplete or invalid. Please check your details. | Agent kann selbst korrigieren | - |
APPROVAL_ALREADY_DECIDED | - | Dieser Brief wurde bereits freigegeben, abgelehnt oder storniert. Eine zweite Entscheidung über denselben Freigabe-Eintrag ist nicht mehr möglich. | Agent kann selbst korrigieren | - |
AVV_REQUIRED | 422 | Bevor du Briefe mit personenbezogenen Daten Dritter versenden kannst, musst du den Auftragsverarbeitungsvertrag (AVV) nach Art. 28 DSGVO abschließen. EN: Before you can send letters containing third-party personal data, you must sign the data processing agreement (AVV, Art. 28 GDPR). | Korrektur im Dashboard nötig | ✓ |
CONTENT_REJECTED | - | Der Inhaltsfilter hat den Brieftext abgelehnt, zum Beispiel wegen eines gesperrten Begriffs. Der Versand wurde nicht gestartet, es wurde nichts berechnet. Der Inhaltsfilter läuft auch im Sandbox-Modus unverändert, ein Test-Token umgeht ihn nicht. | Agent kann selbst korrigieren | - |
COST_OVER_LIMIT | 422 | Die Kosten für diesen Brief liegen über deinem gesetzten Maximalbetrag. Bitte erhöhe das Limit oder reduziere den Umfang. EN: The cost of this letter exceeds the maximum amount you set. Please raise the limit or reduce the scope. | Agent kann selbst korrigieren | - |
COUNTRY_NOT_SUPPORTEDPingenInternational | 422 | Dieses Land wird derzeit nicht unterstützt. EN: This country is currently not supported. | Agent kann selbst korrigieren | - |
DAILY_CAP_EXCEEDED | 429 | Du hast dein Tageslimit für den Versand erreicht. Bitte versuche es nach dem nächsten Reset erneut oder passe dein Limit an. EN: You have reached your daily sending limit. Please try again after the next reset or adjust your limit. | Abwarten und erneut versuchen | - |
DESIGN_NOT_FOUND | 404 | Das angegebene Briefdesign wurde nicht gefunden. EN: The specified letter design was not found. | Agent kann selbst korrigieren | - |
DESIGN_RENDER_FAILED | 422 | Das Briefdesign konnte nicht gerendert werden. Der Versand wurde abgebrochen und nichts berechnet. EN: The letter design could not be rendered. The send was aborted and nothing was charged. | Agent kann selbst korrigieren | - |
DESIGN_ZONE_VIOLATION | 422 | Das Briefdesign verletzt eine geschuetzte Zone und wuerde die Zustellung gefaehrden. Details siehe violations. EN: The letter design violates a protected zone and would jeopardize delivery. See violations for details. | Agent kann selbst korrigieren | - |
FORBIDDEN_BY_MODE_POLICY | - | Dieses Tool verändert einen Zustand, aber der Aufruf lief mit dem Header X-FrankKi-Mode: kanzlei, der nur Lesezugriffe und Freigabeentscheidungen erlaubt. | Agent kann selbst korrigieren | - |
FORBIDDEN_SCOPE | - | Dein Token trägt nicht den Scope, den dieses Tool voraussetzt. | Korrektur im Dashboard nötig | - |
IDEMPOTENCY_CONFLICT | - | Die clientOrderId wurde bereits einmal mit anderen Argumenten verwendet. Derselbe Wert mit denselben Argumenten liefert stattdessen isReplay: true zurück. | Agent kann selbst korrigieren | - |
INSUFFICIENT_FUNDS | - | Dein Wallet-Guthaben reicht für diesen Versand nicht aus. Ein Sandbox-Versand (isTest) prüft dieses Limit nicht, weil er ohnehin 0 Cent bucht. | Korrektur im Dashboard nötig | ✓ |
INTERNAL_ERROR | - | Ein unerwarteter Fehler auf unserer Seite. Es wurde kein Brief versendet und nichts berechnet. | Abwarten und erneut versuchen | - |
LEGAL_PROOF_UNAVAILABLE_FOR_COUNTRYPingenInternational | 422 | Für dieses Land ist kein Einschreiben mit Zustellnachweis verfügbar. EN: A registered letter with proof of delivery is not available for this country. | Agent kann selbst korrigieren | - |
MANDANT_CAP_EXCEEDED | 429 | Für diesen Mandanten ist das Monatslimit erreicht. Bitte erhöhe das Limit oder versende den Brief im nächsten Abrechnungszeitraum. EN: The monthly limit for this client has been reached. Please raise the limit or send the letter in the next billing period. | Korrektur im Dashboard nötig | ✓ |
METHOD_NOT_ALLOWED | - | Die REST-Variante der Partner-Schnittstelle erlaubt nur POST. | Agent kann selbst korrigieren | - |
NOT_FOUND | - | Die angefragte Ressource existiert nicht oder gehört nicht zu deinem Partnerkonto. | Agent kann selbst korrigieren | - |
ORDER_NOT_FIXABLE | 409 | Dieser Brief wartet nicht auf eine Korrektur oder der Fehler lässt sich nicht durch eine neue Empfängeradresse beheben. Prüfe den Status mit order_status. EN: This letter is not awaiting a correction, or the problem cannot be fixed by a new recipient address. Check the status with order_status. | Korrektur im Dashboard nötig | ✓ |
PDF_LETTER_UNSUPPORTED | 422 | Der Versand fertiger PDF-Briefe wird nicht unterstützt. Übermittle stattdessen Betreff und Text deines Briefs, FrankKi setzt ihn automatisch ins DIN-5008-Layout. EN: Sending finished PDF letters is not supported. Provide the subject and body text of your letter instead and FrankKi typesets it in the DIN 5008 layout. | Agent kann selbst korrigieren | - |
PRICE_CHANGED | 409 | Der Preis hat sich seit deinem Angebot geändert. Bitte hole ein neues Angebot ein. EN: The price has changed since your quote. Please obtain a new quote. | Abwarten und erneut versuchen | - |
PRICE_UNAVAILABLEPingenInternational | 503 | Der Preis kann gerade nicht ermittelt werden. Bitte versuche es später erneut. EN: The price cannot be determined right now. Please try again later. | Abwarten und erneut versuchen | - |
RATE_LIMITED | - | Zu viele Anfragen in kurzer Zeit auf der Transportebene. | Abwarten und erneut versuchen | - |
SANDBOX_DISABLED | 403 | Der Sandbox-Modus ist derzeit deaktiviert. Wende dich an den Support oder versuche es später erneut. EN: Sandbox mode is currently disabled. Please contact support or try again later. | Abwarten und erneut versuchen | - |
SENDER_PFLICHTANGABEN_INCOMPLETE | 422 | Dein Absenderprofil ist unvollständig. Bitte ergänze die fehlenden Pflichtangaben, bevor du den Brief versendest. EN: Your sender profile is incomplete. Please add the missing mandatory details before you send the letter. | Korrektur im Dashboard nötig | ✓ |
TEMPLATE_READONLY_VIA_MCP | - | Vorlagen werden ausschließlich im Web-Dashboard gepflegt (Web-Primacy). Über die Partner-Schnittstelle können Vorlagen nur gelesen, nie verändert werden. | Korrektur im Dashboard nötig | - |
UNAUTHORIZED | - | Der Token ist ungültig, abgelaufen oder wurde widerrufen. | Korrektur im Dashboard nötig | - |
VALIDATION_ERROR | - | Die gesendeten Argumente entsprechen nicht dem Schema des Tools: ein Pflichtfeld fehlt, ein Typ stimmt nicht, oder ein unbekanntes Feld wurde mitgeschickt. | Agent kann selbst korrigieren | - |
Vertrauen und Live-Status
Maschinenlesbare Servicefakten und der aktuelle Betriebsstatus der Partner-Schnittstelle stehen jederzeit offen zur Verfügung, ohne Login.