Errors · FinBaze for Platforms

Reference

GraphQL errors carry a top-level extensions.code. Branch on the code, not the message. The REST routes (bulk jobs, statement files, downloads) answer { "error": { "type", "code", "message", "param", "request_id" } } with the same codes. Every response has an X-Request-Id header; send it to support. This page lists 159 codes.

Embed sessions and tokens#

Code	HTTP	Meaning	What to do
`EMBED_SECRET_INVALID`	401	The client secret is malformed or unknown.	Create a new session and pass its `clientSecret` unchanged. Never reuse or edit a secret.
`EMBED_SECRET_USED`	403	The client secret was already exchanged.	Secrets are single use. Return a new secret from `fetchClientSecret` every time; do not cache it.
`EMBED_SECRET_EXPIRED`	403	The client secret was not exchanged within its lifetime (15 minutes).	Create the session as late as possible, in `fetchClientSecret`.
`EMBED_SESSION_REVOKED`	401	The session was revoked, or the user lost access or was disabled.	The SDK asks `fetchClientSecret` for a new session once (`reason: "revoked"`). If your backend refuses, `onSessionExpired` fires.
`EMBED_ORIGIN_NOT_ALLOWED`	403	The page's origin is not in the platform's allowed origins (or not the session's `origin`).	Add the origin in the developer portal under Embedding → Allowed origins. Test and live origins are separate.
`EMBED_COMPONENT_NOT_ALLOWED`	403	The component is not part of this session.	Include it in `components` when you create the session.
`EMBED_OPERATION_NOT_ALLOWED`	403	An embed token tried to run a GraphQL document that is not in the operations manifest.	Embed tokens only run FinBaze's own operations. Use the server API or a headless session for custom queries.
`EMBED_FEATURE_DISABLED`	403	A component feature (for example `submit`) is switched off for this session.	Enable it in the session's `components.<name>.features`.
`EMBED_CHAIN_EXPIRED`	403	A chain of refreshed sessions reached its maximum lifetime (12 hours by default).	The user signs in again in your product; mint a session without `previousSessionId`.
`EMBED_APP_MISMATCH`	403	The session was created for a different channel: a mobile session was used on the web embed, a web session on the mobile shell, or the wrong app id was named.	Create the session with the same `mobileAppId` (or none, for web) that you use to open it, and pass that app id to the mobile SDK.
`PLATFORM_HEADLESS_DISABLED`	403	Headless sessions are not enabled for this platform.	Ask FinBaze to enable `platforms.headless`, then add the origin as a headless origin.
`UNAUTHENTICATED`	401	Missing, expired or revoked token.	Request a new token. The embed SDK maps this to `EMBED_SESSION_REVOKED`.
`FORBIDDEN_TOKEN_TYPE`	403	This kind of token cannot call the operation, for instance a server token calling `grantTaxAuthorisation`.	Consent is given by the company's own user in an embed or headless session.
`SERVER_TOKEN_REQUIRED`		Only a platform server token can use this endpoint (data ingestion over HTTP).	Call it with your secret or restricted key's token, not a user, embed or headless token.
`SCOPE_MISSING`		The key or token lacks the scope the endpoint needs.	Add the scope named in the message to the restricted key, or use a secret key.

Code	HTTP	Meaning	What to do
`TAX_AUTHORISATION_REQUIRED`	403	A return was submitted for a platform company that has not authorised FinBaze to file this tax (or revoked it).	The company's admin authorises it in the `onboarding` or `tax-authorisation` component (or your headless UI). See Filing consent.
`TAX_AUTHORISATION_STATEMENT_OUTDATED`	409	The statement hash or version sent with `grantTaxAuthorisation` is not the text FinBaze would show now.	Load `taxAuthorisationStatement` again, show it and send back its `version` and `hash`.
`TAX_NOT_REGISTERED`	422	A grant named a tax the company has no obligation for.	Offer only the taxes in `taxAuthorisationStatus`.
`FILING_DELEGATED_TO_FIRM`	403	The company's accountant files this return, so the company cannot submit it.	Hide the submit button; the accountant files it.
`FILER_MUST_BE_INTERMEDIARY`	400	The request (the corporate income tax deferral, `nl_cit_uitstel`) can only be filed by a tax intermediary with a BECON number. FinBaze files as a software supplier without a BECON number, so for a company with no accountant it is refused.	Show it as a blocked reason, not a failure: the company's accountant files the deferral. `taxFilingSubmitPreview.blockedReason` carries the same code.
`FIRM_NOT_AUTHORISED_FOR_TAX`	403	A firm tried to file a tax its engagement does not cover.	The company has to extend the engagement.
`STEP_UP_REQUIRED`	403	Your `step_up` provider lists this action and no valid confirmation came with the request. `extensions.challenge` is what to confirm.	Confirm the user, sign the assertion and retry with `FinBaze-Step-Up: <challengeId>.<jws>`. See Delegated actions.
`STEP_UP_CONFIG`		The platform's `step_up` provider is not configured completely.	Register the provider with `jwksUrl` (https) or `keys`.
`STEP_UP_EXPIRED`		The challenge or the assertion is past its lifetime (five minutes for a challenge, `maxAgeSeconds` for an assertion).	Start the action again to get a new challenge, and sign the assertion with a short expiry.
`STEP_UP_INVALID`		The assertion could not be verified: wrong signature, algorithm, issuer, audience or key id.	Sign with `ES256`, `EdDSA` or `RS256`, `iss` = your platform id, `aud` = `finbaze`, and a `kid` your `jwksUrl` or `keys` serves.
`STEP_UP_MISMATCH`		The assertion names another challenge, nonce, action or user than the one being confirmed.	Copy `challenge_id`, `nonce` and `action` from the challenge and set `sub` to the user it was for. A challenge works once.
`FEATURE_NOT_ALLOWED`		The feature a provider or action needs (for example `delegated.step_up`) is not in this platform's allowance.	Ask FinBaze to add it to your allowance.

Sending data#

Code	HTTP	Meaning	What to do
`INVALID_LINE`		One object of a call or bulk line could not be processed; `path` points at the field.	Fix the field named in `path` and send the line again. In a bulk job the other lines were applied.
`INVALID_METADATA`		`metadata` is not up to 50 string values.	Send only strings, at most 50 keys.
`UNKNOWN_COMPANY`	404	The `company` reference matches no company of your platform.	Use the company's `id` or the `externalId` you gave it.
`UNKNOWN_REFERENCE`		A reference to another object (a relation, product, project, employment) is not found for this company.	Send the referenced object first, or fix the `externalId`.
`FEATURE_DISABLED`	403	The company's plan or the platform's limits hide this part of FinBaze, or FinBaze for Platforms is not enabled.	Check the company's effective features (`platformCompanyFeatures`). See Features and limits.
`OBJECT_FINALISED`	409	The object is final (a finalised invoice, approved hours) and accepts `metadata` only.	Correct a finalised invoice with a credit note (`creditOf`).
`OBJECT_DELETED`	409	You deleted this object earlier.	Add `restore: true` to bring it back.
`UNSUPPORTED_OPERATION`		The operation or document kind is not supported yet.	See the operation's description or the changelog for what is available.
`TOTAL_MISMATCH`		`expectedTotalMinor` differs from what your prices and tax codes add up to.	Check the prices and tax codes. Tax is derived from the tax code, never taken from the line.
`AMOUNT_OUT_OF_RANGE`		An amount is outside the range FinBaze stores.	Check that amounts are in minor units.
`CURRENCY_MISMATCH`		A transaction or balance has another currency than its account.	Send each account's currency.
`EXTERNAL_ID_TAKEN`		`externalId` is already used by another company of your platform.	Use a unique `externalId`, or call again with the same id to get the same company.
`LEGAL_NAME_REQUIRED`		`legalName` is required when the register lookup has no match.	Send `legalName`.
`COMPANY_NOT_FOUND`		No such company for your platform.	Check the id. Another platform's company looks the same as one that does not exist.
`INGESTION_PAUSED`	503	Ingestion is paused. Try again later.	Retry later with the same `Idempotency-Key`.
`IDEMPOTENCY_KEY_IN_USE`	409	An upload with this `Idempotency-Key` is still in progress.	Wait for it, then read the job; do not send it again.
`IDEMPOTENCY_KEY_REUSED`	409	This `Idempotency-Key` was used with a different body.	Use a new key for a different body.
`PAYLOAD_TOO_LARGE`	413	The body is larger than the request limit.	Split the file into several bulk jobs.
`UNSUPPORTED_MEDIA_TYPE`	415	The content type is not accepted.	Send NDJSON (`application/x-ndjson`, optionally gzip), or the file types the endpoint lists.
`UNKNOWN_OBJECT`		The bulk job's `object` is not one of the supported names.	Use one of the names the message lists: `relations`, `products`, `projects`, `cost_centers`, `sales_invoices`, `purchase_invoices`, `journal_entries`, `employees`, `employments`, `worked_hours`.
`INVALID_PARAMETER`		A query parameter is missing or not one of the allowed values.	Fix the parameter the message names.
`INVALID_INPUT`		An argument is invalid; the message says which.	Fix the argument.
`BAD_USER_INPUT`	400	An argument failed validation. `extensions.param` names the argument.	Fix the input; the message says what is wrong.
`INTERNAL`	500	FinBaze could not process the line or run.	Retry with the same ids. If it persists, send the `X-Request-Id` to support.

Data sources and feeds#

Code	HTTP	Meaning	What to do
`DATA_SOURCE_KEY_TAKEN`		A data source with this key already exists.	Use the existing source, or another key.
`SOURCE_INACTIVE`		The data source is paused or retired.	Register a new source, or reactivate it in the portal.
`NOT_ATTACHED`		The source is not attached to this company.	Call `attachDataSource` for the company first.
`UNKNOWN_ACCOUNT`	404	The feed account is not known for this company.	Create it with `upsertFeedBankAccount` before sending transactions.
`PENDING_NOT_BOOKED`		Pending transactions are not accepted.	Send a transaction once the bank has booked it.
`IMMUTABLE_TRANSACTION`	409	A booked transaction changed after it was delivered.	Send a reversal (`reverses`) and a new transaction instead.
`EMPTY_FILE`		The statement file is empty.	Check the export.
`FILE_TOO_LARGE`	413	The statement file is over the size limit.	Split the file.
`DESTINATION_KEY_TAKEN`		An export destination with this key exists.	Use another key, or update the existing destination.
`DESTINATION_IN_USE`		An active export schedule still writes to this destination.	Delete or pause the schedule first.
`SCHEDULE_KEY_TAKEN`		An export schedule with this key exists.	Use another key, or update the schedule.

Records and flows#

Code	Meaning	What to do
`UNKNOWN_RECORD_TYPE`	A flow template or record names a record type that is not defined.	Define it with `definePlatformRecordType` first.
`UNKNOWN_STATE`	A trigger names a state that is not a state of the record type.	Use the states you defined.
`UNKNOWN_TAX_CODE`	A template table names a tax code that does not exist.	Use a code from the tax code list.
`UNKNOWN_LEDGER`	A ledger the template names does not exist in the company's chart.	Fix the ledger code in `ledgers`, or activate the template for companies whose chart has it.
`INVALID_TEMPLATE`	The flow template is not valid: the message has the path and line.	Fix the template; `testFlowTemplate` checks it without writing anything.
`INVALID_TRANSITION`	A record or payment request cannot move to that state from where it is.	Send a state the record type allows from the current one.
`CUSTOM_FIELDS_INVALID`	Custom field values do not match their definitions.	Check the definitions with `customFieldDefinitions`.
`CUSTOM_FIELD_LIMIT`	The number of custom field definitions reached the limit.	Archive one you do not use.

Messages, policies and extensions#

Code	Meaning	What to do
`FIELD_CONTROL_INVALID`	A field control (hidden, read-only, required) is not valid.	Fix the control named in the message.
`FIELD_LOCKED`	A field is locked by the platform's field controls.	Do not change it from this surface, or lift the control.
`COPY_TEMPLATE_INVALID`	A message copy template has problems (unknown placeholders, too long, links in model text).	Fix what the message lists; `previewPlatformMessageCopy` renders it first.
`ROUTING_NOT_ALLOWED`	The message type cannot be routed that way (the catalogue lists the allowed routings per type).	Choose one of the type's allowed routings.
`PREFERENCE_LOCKED`	Account-security email cannot be switched off.	Leave that preference on.
`UNKNOWN_PARTNER_ROLE`	The platform has no such role in its `roles_mapping` policy.	Add the role to the policy, or send a role it has.
`ROUTING_NOT_CHANGEABLE`	Lifecycle, billing and account-security messages are never delivered for platform companies and their routing cannot be changed.	Leave the rule out. See the message catalogue.
`POLICY_INVALID`	A policy in the bundle is not valid.	Fix the policy the message names.
`POLICY_NOT_OVERRIDABLE`	This kind of policy cannot be overridden per company.	Change it for the whole platform.
`QUOTA_EXCEEDED`	The monthly quota of the feature is used up.	Wait for the next month or ask for a higher quota.
`FILING_APPROVAL_NOT_ENABLED`	Approval applies only to companies of a platform with dual approval.	Enable dual approval in the filing policy first.
`FILING_APPROVAL_REQUIRED`	The person who prepared a filing cannot approve it.	Let a second person approve it.
`FILING_NOT_READY`	Only a filing that is ready can be approved.	Finish the draft first.
`FILING_SUBMIT_ROLE`	The user's role cannot approve tax filings for this company.	Use a user with the role the policy requires.
`CUSTOM_ACTION_INVALID`	A custom action is not valid.	Fix the definition the message describes.
`LINK_TEMPLATE_INVALID`	A link template is not valid.	Use an https URL with the placeholders the message lists.
`SLOT_INVALID`	The extension slot does not exist or does not accept this item.	Use a slot from `platformCustomActions` / the slot list.

Webhooks and events#

Code	HTTP	Meaning	What to do
`ALREADY_DELIVERED`		This event was already delivered to the endpoint.	Replay that delivery instead of resending the event.
`ENDPOINT_DISABLED`		The endpoint is disabled.	Enable it (and fix the cause: a `410 Gone` or repeated failures disable it) before replaying.

Payments and delegated actions#

Code	Meaning	What to do
`PROVIDER_NOT_REGISTERED`	This platform has no enabled provider for the action.	Register one with `upsertPlatformProvider`.
`PROVIDER_CONFIG_INVALID`	The provider's configuration is not valid (for example `step_up` needs `jwksUrl` or `keys`).	Fix the configuration the message names.
`PROVIDER_KIND_NOT_ENABLED`	The payments provider does not handle this kind of request.	Add the kind to the provider's `kinds`.
`PAYMENT_REQUEST_EMPTY`	The batch has no payable lines (held and blocked lines are excluded).	Release or fix the lines.
`PAYMENT_REQUEST_INVALID_LINE`	Every line needs a verified IBAN snapshot and a positive amount.	Verify the creditor's bank details in FinBaze.
`PAYMENT_REQUEST_NOT_PAYABLE`	The filing must be submitted or accepted before it can be paid.	Create the request after the filing is submitted.
`PAYMENT_REQUEST_UNSUPPORTED`	Only NL VAT and wage tax filings can be paid through a request.	Pay other taxes outside FinBaze.
`STATUS_NOT_REPORTABLE`	A partner can report `sent`, `accepted`, `scheduled`, `failed` or `cancelled`; `paid` comes from the bank.	Push the bank transaction with its `endToEndId`; the request becomes paid by itself.
`PAYMENT_LINK_INVALID`	The payment link is not an https URL on one of your `allowedHosts`.	Add the host to the provider config or fix the URL.

Accounting firms#

Code	Meaning	What to do
`FIRM_ACCESS_DISABLED`	`firm_access` is hidden for the company.	Show the key again (Features and limits).
`FIRM_NOT_FOUND`	No firm matches the KvK number or connect code.	Check the number; lookups are exact.
`FIRM_HAS_NO_BECON`	Taxes were chosen, but the firm has no BECON number.	Offer bookkeeping access only.
`FIRM_ENGAGEMENT_STATEMENT_OUTDATED`	The statement changed since it was shown.	Read `firmEngagementStatement` again and confirm the new text.
`ENGAGEMENT_NOT_PENDING`	The request was already answered or expired.	Reload the engagement.
`ENGAGEMENT_NOT_ACTIVE`	The engagement is not active.	Reload the engagement.
`COMPANY_ADMIN_REQUIRED`	The user is not an admin of the company.	A company admin has to do this.
`FIRM_ADMIN_REQUIRED`	The user is not an admin of the firm.	A firm admin has to do this.
`FIRM_LOOKUP_RATE_LIMITED`	Too many firm lookups or requests for this company.	Wait and try again; limits are per hour.
`PLATFORM_END_REASON_NOT_ALLOWED`	A platform ended an engagement with a reason that is not in its list.	Use `firm_access_hidden`, `company_closed`, `company_transferred` or `platform_request`.
`PLATFORM_COMPANY_USE_ENGAGEMENT`	A firm tried to connect a platform company through an invite link, onboarding or `createClient`.	Connect it through an accountant connection: the company invites the firm, or the firm requests access.
`NOT_A_PLATFORM_COMPANY`	The company does not belong to a platform.	Use the operations for direct companies.

Company lifecycle and transfers#

Code	Meaning	What to do
`COMPANY_SUSPENDED`	The company is suspended and read-only.	Reactivate it with `reactivatePlatformCompany`.
`COMPANY_CLOSED`	The company stopped trading; only final returns and exports still work.	Reopen it within the reopen window, or leave it.
`COMPANY_ARCHIVED`	The company is archived; only exports work.	Export what you need.
`INVALID_LIFECYCLE_TRANSITION`	The company's state does not allow this move.	Read `lifecycle.state` first.
`SUSPENDED_BY_FINBAZE`	FinBaze suspended the company; only FinBaze can reactivate it.	Contact support.
`INVALID_EFFECTIVE_DATE`	The closing date is not valid.	Use a date the closing checklist accepts.
`REOPEN_WINDOW_PASSED`	The reopen window (90 days by default) has passed.	The company cannot be reopened.
`ARCHIVE_BLOCKED`	A blocking closing checklist item is open.	Complete it; `companyClosingChecklist` lists them.
`FORCE_NOT_ALLOWED`	Only FinBaze staff can force this move.	Do not pass `force`.
`TRANSFER_CODE_INVALID`	The transfer code is wrong, used or unknown (they all fail the same way).	Ask the sending platform for a new code.
`TRANSFER_CODE_EXPIRED`	The transfer code expired (14 days by default).	Start the transfer again.
`TRANSFER_ALREADY_PENDING`	The company already has a pending transfer.	Cancel it with `cancelCompanyTransfer`.
`TRANSFER_TO_SAME_PLATFORM`	The target is the platform that owns the company.	Choose another target.
`TRANSFER_WRONG_TARGET`	The code is for another kind of target.	Use `acceptCompanyTransfer` for platform codes and the claim link for direct transfers.
`TRANSFER_STATEMENT_OUTDATED`	The transfer statement changed since it was shown.	Show it again and send the new hash.
`TRANSFER_EMAIL_REQUIRED`	A transfer to direct FinBaze needs an email address.	Send `email`.
`TRANSFER_EMAIL_MISMATCH`	The account claiming the company does not have the email the transfer was made for.	Sign in with that address.

Support access#

Code	Meaning	What to do
`SUPPORT_ESCALATION_DISABLED`	Escalation to FinBaze support is not enabled for the platform.	Switch the support mode in the portal.
`ESCALATION_CLOSED`	The support escalation is closed.	Open a new one.
`SUPPORT_MODE_FINBAZE_DIRECT`	Support goes to FinBaze directly for this platform; there is no partner-first step.	Use the escalation form or `createSupportEscalation`.
`SUPPORT_NOT_A_PLATFORM_COMPANY`	Support access applies to platform companies only.	Use the normal support channels.
`SUPPORT_COMPANY_ADMIN_REQUIRED`	Only a company admin decides on support access.	Ask an admin.
`SUPPORT_GRANT_ALREADY_OPEN`	A support access request or grant is already open for the company.	Answer or end the open one first.
`SUPPORT_GRANT_NOT_FOUND`	No such support access grant.	Check the id.
`SUPPORT_GRANT_NOT_PENDING`	The grant was already answered.	Reload it.
`SUPPORT_GRANT_NOT_ACTIVE`	The grant is not active (expired, revoked or declined).	Ask for a new one.
`SUPPORT_GRANT_REQUIRED`	FinBaze staff need the company's consent before viewing it.	Approve the request in `support-access`.
`SUPPORT_GRANT_READ_ONLY`	Support access is read-only.	Support staff cannot change data.
`SUPPORT_GRANT_DENIED_OPERATION`	The operation is not available through support access.	Support staff cannot do this on the company's behalf.
`SUPPORT_ATTESTATION_REQUIRED`	A break-glass access needs the staff member's attestation.	Add the attestation.
`SUPPORT_BREAK_GLASS_SECOND_ADMIN_REQUIRED`	Break-glass access needs a second FinBaze admin to confirm.	Ask a second admin.
`INVALID_DURATION`	The access duration is outside the allowed range.	Choose a shorter or longer period.
`INVALID_REASON`	The reason is missing or not one of the allowed values.	Send a reason.

Sandbox#

Code	Meaning	What to do
`TEST_CLOCK_NOT_FOUND`	No such test clock for your platform.	List clocks with `testClocks`.
`TEST_CLOCK_LIMIT`	The platform reached its maximum number of test clocks.	Delete one with `deleteTestClock`.
`TEST_CLOCK_BACKWARDS`	A test clock only moves forward.	Create a new clock for an earlier time.
`TEST_CLOCK_RANGE_TOO_LARGE`	The requested advance is longer than the maximum (400 days by default).	Advance in several steps.
`TEST_CLOCK_BUSY`	The clock is still advancing.	Wait until its status is `ready` again.
`SANDBOX_ONLY`	This operation (test clocks, demo companies, sample apps, the reset) is available in the sandbox only.	Call the sandbox API (`https://sandbox.api.platform.finbaze.com`) with a test key.
`SANDBOX_RESET_RUNNING`	A reset of this sandbox is already running.	Wait for it to finish.
`SANDBOX_SIGN_IN_ONLY`	Sandbox access is through your production FinBaze account.	Sign in with your production account.
`MIRRORED_FROM_PRODUCTION`	This sandbox object mirrors production and cannot be changed in the sandbox.	Change it in production.

Platform, keys and limits#

Code	HTTP	Meaning	What to do
`KEY_LIMIT_REACHED`		A platform can have at most 10 active keys per environment.	Revoke a key you no longer use.
`RATE_LIMITED`	429	Too many requests in the window (also: 5 sample apps a day).	Back off and retry.
`FORBIDDEN`	403	The key or token may not do this.	Check the key's scopes and the company's features.
`NOT_FOUND`	404	The object does not exist for your platform. Another platform's object looks the same.	Check the id.
`CONFLICT`	409	The request conflicts with the current state.	Read the object and decide again.
`UNPROCESSABLE`	422	The request is well-formed but cannot be processed.	Read the message.
`UNAVAILABLE`	503	The service cannot answer now.	Retry with the same idempotency key.

In the browser SDK#

FinBazeEmbedError has the same code values plus the message. Pass onError to loadFinBaze to receive them; per-component failures also arrive as the component's error event.