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 Kapitel Weltweiter Versand) 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. | Agent kann selbst korrigieren | - |
AGENT_SELF_APPROVAL_NOT_GRANTED | 403 | Dieser Agent darf Briefe nicht selbst freigeben. Öffne die Freigabe im Browser und entscheide dort. Wenn der Agent das künftig übernehmen soll, verbinde ihn erneut und erlaube die selbstständige Freigabe ausdrücklich. | Korrektur im Dashboard nötig | ✓ |
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. | Korrektur im Dashboard nötig | ✓ |
BRAND_IMPORT_ROBOTS_DISALLOWED | 422 | Die Website erlaubt automatisiertes Auslesen dieser Seite nicht (robots.txt). Lade Logo und Farben bitte direkt im Design Studio hoch. | 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. | 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. | Agent kann selbst korrigieren | - |
COUNTRY_NOT_SUPPORTEDWeltweiter Versand | 422 | Dieses Land wird derzeit nicht unterstützt. | 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. | Abwarten und erneut versuchen | - |
DESIGN_NOT_FOUND | 404 | Das angegebene Briefpapier wurde nicht gefunden. | Agent kann selbst korrigieren | - |
DESIGN_RENDER_FAILED | 422 | Das Briefpapier konnte nicht gerendert werden. Der Versand wurde abgebrochen und nichts berechnet. | Agent kann selbst korrigieren | - |
DESIGN_ZONE_VIOLATION | 422 | Das Briefpapier verletzt eine geschuetzte Zone und wuerde die Zustellung gefaehrden. Details siehe violations. | Agent kann selbst korrigieren | - |
DOCUMENT_EXPORT_NOT_READY | 422 | Der elektronische Rechnungsexport (ZUGFeRD, XRechnung) ist noch nicht verfügbar. Das gedruckte Dokument und seine Belegdaten kannst du bereits nutzen. | Abwarten und erneut versuchen | - |
DOCUMENT_EXPORT_NOT_SUPPORTED | 422 | Für diesen Dokumenttyp gibt es keine E-Rechnung. Mahnung und Zahlungserinnerung wiederholen eine bereits gestellte Forderung und sind nach EN 16931 keine Rechnung; ZUGFeRD und XRechnung gibt es nur für Rechnung und Gutschrift. | Agent kann selbst korrigieren | - |
DOCUMENT_FIELD_MISSING | 422 | Dem Dokument fehlt eine gesetzliche Pflichtangabe (§ 14 UStG). Unter details.issues und missingFields steht, was fehlt; über fixUrl ergänzt du es. | Korrektur im Dashboard nötig | ✓ |
DOCUMENT_MATH_MISMATCH | 422 | Die Summen im Dokument gehen nicht auf. Unter details.issues steht je Feld, welcher Wert erwartet wurde und welcher angegeben ist. | Agent kann selbst korrigieren | - |
DOCUMENT_NOT_FOUND | 404 | Dieses Dokument wurde nicht gefunden. Prüfe die documentId mit document_list. | Agent kann selbst korrigieren | - |
DOCUMENT_NUMBER_DUPLICATE | 409 | Diese Belegnummer ist in deinem Nummernkreis bereits vergeben und gehört zu einem anderen Dokument. Wähle eine andere Nummer oder lass FrankKi eine aus deinem Nummernkreis ziehen. | Agent kann selbst korrigieren | - |
DOCUMENT_SEQUENCE_MISSING | 422 | Für diesen Nummernkreis ist kein Zähler eingerichtet oder er ist abgeschaltet. Richte ihn im Dashboard ein oder gib die Belegnummer selbst als documentNumber an. | Korrektur im Dashboard nötig | ✓ |
DOCUMENT_TYPE_NOT_READY | 422 | Für diesen Dokumenttyp gibt es noch kein Layout. FrankKi erzeugt aktuell nur Rechnungen aus strukturierten Belegdaten; Mahnung, Zahlungserinnerung und Gutschrift folgen. | Abwarten und erneut versuchen | - |
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 | 403 | Dein Token trägt nicht das Recht, das dieses Tool voraussetzt. Rechte werden beim Erstellen fest in den Token geschrieben und lassen sich nicht nachträglich ergänzen. Erstelle im Dashboard einen neuen Token mit diesem Recht oder ersetze den bestehenden. | Korrektur im Dashboard nötig | ✓ |
FORMAT_UNAVAILABLE_FOR_COUNTRY | 422 | Diese Kombination aus Seitenzahl, Farbe und Versandart ist für das Zielland nicht verfügbar. Reduziere den Umfang oder ändere die Versandoptionen. | Agent kann selbst korrigieren | - |
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 | 402 | Dein Guthaben reicht für diesen Brief nicht aus. Die Antwort nennt unter details den Kontostand, den benötigten Betrag und den Fehlbetrag sowie unter details.suggestedTopup einen passenden Aufladebetrag für wallet_topup_link. Bezahlt wird immer im Browser, nie im Chat. | 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_COUNTRYWeltweiter Versand | 422 | Für dieses Land ist kein Einschreiben mit Zustellnachweis verfügbar. | 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. | Korrektur im Dashboard nötig | ✓ |
MERGE_FIELDS_MISSING | 422 | Erforderliche Vorlagenfelder fehlen oder sind ungültig. Prüfe details.unfilledMergeFields und details.invalidMergeFields, ergänze oder korrigiere diese Werte und rufe das Tool erneut auf. | Agent kann selbst korrigieren | - |
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. | 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. | Agent kann selbst korrigieren | - |
PRICE_CHANGED | 409 | Der Preis hat sich seit deinem Angebot geändert. Bitte hole ein neues Angebot ein. | Abwarten und erneut versuchen | - |
PRICE_UNAVAILABLEWeltweiter Versand | 503 | Der Preis kann gerade nicht ermittelt werden. Bitte versuche es später erneut. | 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. | Abwarten und erneut versuchen | - |
SENDER_PFLICHTANGABEN_INCOMPLETE | 422 | Dein Absenderprofil ist unvollständig. Bitte ergänze die fehlenden Pflichtangaben, bevor du den Brief versendest. | Korrektur im Dashboard nötig | ✓ |
TEMPLATE_FOUR_EYES_REQUIRED | 403 | Diese Vorlage muss ein Mensch im Dashboard freigeben. Über MCP kannst du nur freigeben, wenn dein Konto genau einen aktiven Nutzer hat (Vier-Augen-Prinzip). | Korrektur im Dashboard nötig | ✓ |
TEMPLATE_READONLY_VIA_MCP | - | Diese Vorlagenänderung lief außerhalb der vier Autoren-Tools (template_save, template_release, template_archive, template_draft_discard) und ist deshalb über die Partner-Schnittstelle nicht möglich. Die vier Autoren-Tools selbst können mit dem Scope template:write Entwürfe schreiben, archivieren und verwerfen, und bei genau einem aktiven Nutzer im Konto auch freigeben; mit mehreren Nutzern bleibt die Freigabe im Web-Dashboard (Vier-Augen-Prinzip). Die Standard-Bibliothek (partnerübergreifende Vorlagen) bleibt in jedem Fall nur lesbar. | Korrektur im Dashboard nötig | - |
TEMPLATE_SLUG_CONFLICT | 409 | Du hast bereits eine Vorlage mit diesem Kurznamen. Bitte wähle einen anderen Namen. | Agent kann selbst korrigieren | - |
TEMPLATE_VERSION_IMMUTABLE | 409 | Diese Version kann nicht verworfen werden. Nur ein Entwurf, der noch nicht freigegeben wurde, lässt sich verwerfen. | Agent kann selbst korrigieren | - |
TEMPLATE_VERSION_NOT_DRAFT | 409 | Diese Version kann nicht freigegeben werden. Nur ein Entwurf kann freigegeben werden. | Agent kann selbst korrigieren | - |
UNAUTHORIZED | - | Der Token ist ungültig, abgelaufen oder wurde widerrufen. | Korrektur im Dashboard nötig | - |
UNKNOWN_COUNTRY | 422 | Der angegebene Ländercode ist kein zugewiesener ISO-3166-1-alpha-2-Code. Prüfe details.country, verwende den gültigen zweistelligen Code des Ziellands und rufe das Tool erneut auf. | Agent kann selbst korrigieren | - |
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.