Error catalog
Every error an agent can hit against the FrankKi partner interface is listed here: its meaning, what you do next, and whether the response carries a fixUrl link. A fixUrl is a deep link into the authenticated web dashboard, straight to the screen that fixes the underlying cause, for example the sender profile or the wallet top-up. That relationship holds for every code in the table and is explained once here, no code below repeats it. You never need to read backend source or file a ticket to recover from any of these.
Meaning and recovery class for the codes sourced as "transport" (token, schema and transport level) are maintained by hand here instead of generated from errors.json, because they have no gate entry in the backend. If that changes, errors.json automatically takes precedence.
These three codes belong to worldwide sending (see PingenInternational) and are defined there conclusively. This table only references their meaning, it does not redefine them.
| Code | HTTP | Meaning | Recovery | Fix 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 can fix it itself | - |
APPROVAL_ALREADY_DECIDED | - | This letter has already been approved, rejected or cancelled. A second decision on the same approval entry is no longer possible. | Agent can fix it itself | - |
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). | Fix needed in the dashboard | ✓ |
CONTENT_REJECTED | - | The content filter rejected the letter text, for example because of a blocked term. The send was never started and nothing was charged. The content filter runs unchanged in sandbox mode too, a test token does not bypass it. | Agent can fix it itself | - |
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 can fix it itself | - |
COUNTRY_NOT_SUPPORTEDPingenInternational | 422 | Dieses Land wird derzeit nicht unterstützt. EN: This country is currently not supported. | Agent can fix it itself | - |
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. | Wait and retry | - |
DESIGN_NOT_FOUND | 404 | Das angegebene Briefdesign wurde nicht gefunden. EN: The specified letter design was not found. | Agent can fix it itself | - |
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 can fix it itself | - |
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 can fix it itself | - |
FORBIDDEN_BY_MODE_POLICY | - | This tool changes state, but the call ran with the X-FrankKi-Mode: kanzlei header, which only allows reads and approval decisions. | Agent can fix it itself | - |
FORBIDDEN_SCOPE | - | Your token does not carry the scope this tool requires. | Fix needed in the dashboard | - |
IDEMPOTENCY_CONFLICT | - | The clientOrderId was already used once with different arguments. The same value with the same arguments instead returns isReplay: true. | Agent can fix it itself | - |
INSUFFICIENT_FUNDS | - | Your wallet balance is not enough for this send. A sandbox send (isTest) never checks this limit, since it books 0 cents anyway. | Fix needed in the dashboard | ✓ |
INTERNAL_ERROR | - | An unexpected error on our side. No letter was sent and nothing was charged. | Wait and retry | - |
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 can fix it itself | - |
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. | Fix needed in the dashboard | ✓ |
METHOD_NOT_ALLOWED | - | The REST variant of the partner interface only allows POST. | Agent can fix it itself | - |
NOT_FOUND | - | The requested resource does not exist, or does not belong to your partner account. | Agent can fix it itself | - |
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. | Fix needed in the dashboard | ✓ |
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 can fix it itself | - |
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. | Wait and retry | - |
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. | Wait and retry | - |
RATE_LIMITED | - | Too many requests in a short time at the transport level. | Wait and retry | - |
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. | Wait and retry | - |
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. | Fix needed in the dashboard | ✓ |
TEMPLATE_READONLY_VIA_MCP | - | Templates are authored exclusively in the web dashboard (web primacy). The partner interface can only read templates, never change them. | Fix needed in the dashboard | - |
UNAUTHORIZED | - | The token is invalid, expired, or has been revoked. | Fix needed in the dashboard | - |
VALIDATION_ERROR | - | The submitted arguments do not match the tool schema: a required field is missing, a type is wrong, or an unknown field was sent. | Agent can fix it itself | - |
Trust and live status
Machine-readable service facts and the current operational status of the partner interface are publicly available at all times, no login needed.