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 the Worldwide sending chapter) 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 | The recipient address is incomplete or invalid. Please check your details. | Agent can fix it itself | - |
AGENT_SELF_APPROVAL_NOT_GRANTED | 403 | This agent cannot approve letters on its own. Open the approval in your browser and decide there. To let the agent handle future approvals, reconnect it and explicitly allow self-approval. | Fix needed in the dashboard | ✓ |
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 | 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 | ✓ |
BRAND_IMPORT_ROBOTS_DISALLOWED | 422 | The website does not allow automated reading of this page (robots.txt). Please upload the logo and colours directly in the design studio. | 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. | Agent can fix it itself | - |
COST_OVER_LIMIT | 422 | 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_SUPPORTEDWeltweiter Versand | 422 | This country is currently not supported. | Agent can fix it itself | - |
DAILY_CAP_EXCEEDED | 429 | 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 | The specified letterhead was not found. | Agent can fix it itself | - |
DESIGN_RENDER_FAILED | 422 | The letterhead could not be rendered. The send was aborted and nothing was charged. | Agent can fix it itself | - |
DESIGN_ZONE_VIOLATION | 422 | The letterhead violates a protected zone and would jeopardize delivery. See violations for details. | Agent can fix it itself | - |
DOCUMENT_EXPORT_NOT_READY | 422 | The electronic invoice export (ZUGFeRD, XRechnung) is not available yet. The printed document and its structured payload are already usable. | Wait and retry | - |
DOCUMENT_EXPORT_NOT_SUPPORTED | 422 | There is no e-invoice for this document type. A dunning letter and a payment reminder repeat an already invoiced claim and are not an invoice under EN 16931; ZUGFeRD and XRechnung exist for invoices and credit notes only. | Agent can fix it itself | - |
DOCUMENT_FIELD_MISSING | 422 | The document is missing a mandatory legal detail (§ 14 UStG). details.issues and missingFields name what is missing; the fixUrl takes you to the screen that adds it. | Fix needed in the dashboard | ✓ |
DOCUMENT_MATH_MISMATCH | 422 | The sums in the document do not add up. Under details.issues you find, per field, the expected value and the value you sent. | Agent can fix it itself | - |
DOCUMENT_NOT_FOUND | 404 | This document was not found. Check the documentId with document_list. | Agent can fix it itself | - |
DOCUMENT_NUMBER_DUPLICATE | 409 | This document number is already used in your number circle and belongs to a different document. Choose another number or let FrankKi draw one from your sequence. | Agent can fix it itself | - |
DOCUMENT_SEQUENCE_MISSING | 422 | No counter is set up for this number circle, or it is switched off. Set it up in the dashboard or supply the document number yourself as documentNumber. | Fix needed in the dashboard | ✓ |
DOCUMENT_TYPE_NOT_READY | 422 | There is no layout for this document type yet. FrankKi currently generates invoices only from structured document payloads; dunning letters, payment reminders and credit notes follow. | Wait and retry | - |
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 | 403 | Your token does not carry the scope this tool requires. Scopes are written into the token when it is created and cannot be added later. Create a new token with this scope in the dashboard, or replace the existing one. | Fix needed in the dashboard | ✓ |
FORMAT_UNAVAILABLE_FOR_COUNTRY | 422 | This combination of page count, color and delivery type is not available for the destination country. Reduce the size or change the shipping options. | Agent can fix it itself | - |
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 | 402 | Your balance is not enough for this letter. The response names the balance, the required amount and the shortfall under details, plus a matching top-up amount for wallet_topup_link under details.suggestedTopup. Payment always happens in the browser, never in the chat. | 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_COUNTRYWeltweiter Versand | 422 | A registered letter with proof of delivery is not available for this country. | Agent can fix it itself | - |
MANDANT_CAP_EXCEEDED | 429 | 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 | ✓ |
MERGE_FIELDS_MISSING | 422 | Required template fields are missing or invalid. Check details.unfilledMergeFields and details.invalidMergeFields, add or correct those values, and call the tool again. | Agent can fix it itself | - |
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 | 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 | 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 | The price has changed since your quote. Please obtain a new quote. | Wait and retry | - |
PRICE_UNAVAILABLEWeltweiter Versand | 503 | 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 | Sandbox mode is currently disabled. Please contact support or try again later. | Wait and retry | - |
SENDER_PFLICHTANGABEN_INCOMPLETE | 422 | Your sender profile is incomplete. Please add the missing mandatory details before you send the letter. | Fix needed in the dashboard | ✓ |
TEMPLATE_FOUR_EYES_REQUIRED | 403 | This template must be released by a human in the dashboard. Release via MCP is only possible when your account has exactly one active user (four-eyes principle). | Fix needed in the dashboard | ✓ |
TEMPLATE_READONLY_VIA_MCP | - | This template change ran outside the four authoring tools (template_save, template_release, template_archive, template_draft_discard) and is therefore not possible through the partner interface. The four authoring tools themselves can write, archive and discard drafts with the template:write scope, and can also release when the account has exactly one active user; with several users release stays in the web dashboard (four-eyes principle). The standard library (templates shared across partners) always stays read-only. | Fix needed in the dashboard | - |
TEMPLATE_SLUG_CONFLICT | 409 | You already have a template with this short name. Please choose a different name. | Agent can fix it itself | - |
TEMPLATE_VERSION_IMMUTABLE | 409 | This version cannot be discarded. Only a draft that has not been released yet can be discarded. | Agent can fix it itself | - |
TEMPLATE_VERSION_NOT_DRAFT | 409 | This version cannot be released. Only a draft can be released. | Agent can fix it itself | - |
UNAUTHORIZED | - | The token is invalid, expired, or has been revoked. | Fix needed in the dashboard | - |
UNKNOWN_COUNTRY | 422 | The supplied country code is not an assigned ISO 3166-1 alpha-2 code. Check details.country, use the destination country's valid two-letter code, and call the tool again. | Agent can fix it itself | - |
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.