Fix JTL connection errors

When a JTL authorization does not finish, the hub shows a page with a title, What happened, and What to do. Select Read the troubleshooting guide on that page to open the matching section below, or find the title in the table. A failed attempt saves nothing and leaves an existing connection as it was, so you can always select Try again.

Code	Title on screen	Meaning
callback_mismatch	JTL shows its own error page	The callback URL in the JTL app differs from the one in the hub.
invalid_client	JTL did not accept the app credentials	JTL rejected the client ID or client secret.
missing_scope	Permissions are missing	The app or the authorization lacks the required scopes.
cancelled	Connection cancelled	Access was not approved at JTL.
expired	The authorization expired	The attempt ran out or finished in another browser.
account_mismatch	A different account was used	Another JTL account was used to reconnect.
not_activated	The JTL account is not ready yet	The account has not signed in to the FFN portal or is not a merchant account.
permission_lost	You no longer have access	You lost the Connections permission during the authorization.
reconnect_required	Reconnect needed, on the account card	JTL no longer accepts the stored authorization.
unavailable	JTL is not reachable right now	JTL or the network could not be reached.
failed	The connection could not be completed, or We could not confirm the connection	An unexpected error, or the result could not be confirmed.

The browser’s address bar also shows the code that the hub received, after outcome=.

Information for support

If you contact support, include these details. None of them is secret:

• the time of the attempt, with your time zone
• the workspace name
• the environment: Production or Sandbox
• the client ID of your JTL app
• the callback URL shown in the Connect JTL Fulfillment Network dialog
• the title shown on screen, or the code after outcome= in the address bar

Never send the client secret, your JTL password, or tokens. If you attach a screenshot, make sure it shows none of them.

The callback URL does not match

Code: callback_mismatch

What you see: JTL shows an error instead of its sign-in or consent page, often mentioning the redirect URI. You do not return to the hub. Depending on where JTL checks the address, the hub may instead show JTL did not accept the app credentials.

Likely cause: The redirect URI saved in the JTL app is not exactly the callback URL shown in the Connect JTL Fulfillment Network dialog. Typical differences are a missing or extra slash at the end, http instead of https, spaces, or an address copied from somewhere else.

What to do:

1. In Balta Labs, open Settings → Connections, select Add account, and choose JTL FFN. Under Before you continue, select Copy next to the callback URL.
2. Open the app at kundencenter.jtl-software.de/oauth, replace its redirect URI with the copied one, and save.
3. Return to the hub and select Continue to JTL again. Do not reload JTL’s error page.

For support: the details above and the text of JTL’s error.

JTL rejects the client ID or secret

Code: invalid_client

What you see: The hub shows JTL did not accept the app credentials. JTL may also show an error about the client before you can sign in.

Likely cause: The client ID or client secret does not match an app at JTL. It may be wrong, incomplete, or surrounded by spaces, belong to another app, or the app may have been deleted or its secret replaced. A redirect URI that does not match the callback URL exactly can have the same effect.

What to do:

1. Open the app at kundencenter.jtl-software.de/oauth and copy its client ID and client secret again.
2. Check that its redirect URI matches the callback URL in the hub exactly.
3. For a new connection, open Settings → Connections → Add account → JTL FFN. For an existing one, select Reconnect on its card.
4. Enter both values and select Continue to JTL, or Reconnect with JTL for an existing connection.
5. If JTL still rejects them, create a new app and use its values.

For support: the details above. Check that the client ID you send matches the one in the JTL Customer Center.

Required scopes are missing

Code: missing_scope

What you see: After you approve access, the hub shows Permissions are missing. On an existing account, Test can end with Check failed for the same reason.

Likely cause: The JTL app does not include both ffn.merchant.read and ffn.merchant.write, for example because a template with only fulfiller scopes was chosen. JTL may also have granted less access than requested.

What to do:

1. Open the app at kundencenter.jtl-software.de/oauth.
2. Tick both scopes. If you cannot change them, create a new app with both scopes.
3. In the hub, select Try again, or Reconnect on an existing connection. Enter the new client ID and secret if you created a new app.
4. At JTL, approve all requested permissions.

For support: the details above and the scopes that JTL lists for the app.

The authorization was cancelled

Code: cancelled

What you see: The hub shows Connection cancelled. Nothing was changed.

Likely cause: Access was declined on JTL’s consent page, or JTL returned without granting access.

What to do:

1. Select Try again.
2. Sign in at JTL and approve the access.
3. If you did not decline and it happens again, contact support.

For support: the details above and what you selected on JTL’s page.

The authorization has expired

Code: expired

What you see: The hub shows The authorization expired.

Likely cause: Each attempt is valid for 10 minutes and only in the browser where it started. One of these happened:

• More than 10 minutes passed between Continue to JTL and your return to the hub.
• The sign-in finished in a different browser, browser profile, or device than it started in, or the browser blocked the cookie that the hub uses for the attempt.
• A JTL page was reloaded or reopened from the browser history, so a used attempt arrived a second time.
• JTL no longer accepted its one-time authorization code.
• During a reconnection, the account was removed from the workspace.

What to do:

1. Select Try again in the same browser.
2. Finish the sign-in at JTL within 10 minutes. Do not copy the JTL address into another browser.
3. If it keeps happening, allow cookies for Balta Labs or try another browser.

For support: the details above, your browser, and roughly how long the sign-in took.

A different JTL account was used

Code: account_mismatch

What you see: During a reconnection, the hub shows A different account was used. Nothing was changed.

Likely cause: You signed in at JTL with another account than the connected one, for example a colleague’s login, a sandbox account, or another merchant account. Your browser may also have been signed in to JTL with another account already.

What to do:

1. Select Edit on the account card to see which JTL account the connection uses.
2. Sign out at JTL. Alternatively, open a private browser window and sign in to Balta Labs there.
3. Select Reconnect and sign in with the original JTL account.
4. To use the other JTL account instead, add it as a new connection. Then choose it as the Provider account of your locations in Fulfillment → Setup.

For support: the details above, the JTL account shown under Edit, and the name of the JTL account you signed in with.

The JTL account is not activated

Code: not_activated

What you see: After you approve access, the hub shows The JTL account is not ready yet. On an existing account, Test can end with Check failed and a message that JTL FFN does not know the account yet.

Likely cause: JTL’s API answers not found until the account has signed in to the FFN portal once. The account may also lack the Merchant role, for example because it is a fulfiller account. The environment can also be the cause: a production account must sign in to the production portal, a sandbox account to the sandbox portal.

What to do:

1. With the same JTL account, sign in once at fulfillment.jtl-software.com for production or fulfillment-sandbox.jtl-software.com for the sandbox, and complete the merchant setup.
2. Check that the account has the Merchant role. If you are unsure, ask the account owner or JTL.
3. Check that the Environment you chose in the hub matches that portal.
4. Select Try again.

For support: the details above and whether you can sign in to the matching FFN portal.

You no longer have permission

Code: permission_lost

What you see: You approved access at JTL, but the hub shows You no longer have access and saved nothing.

Likely cause: While you were at JTL, your Connections permission in this workspace was removed, your role changed, or you left the workspace. The hub checks the permission again before saving.

What to do:

1. Ask a workspace owner to give you the Connections permission in Settings → Team.
2. Select Try again, or ask a colleague with that permission to connect the account.

For support: the details above and your role in the workspace.

The account needs to be reconnected

Code: reconnect_required

What you see: The account card shows Reconnect needed, and Edit explains that JTL no longer accepts the stored authorization. Fulfillment work for this account fails until you reconnect.

Likely cause: JTL refused to renew access. This happens when access was revoked at JTL, when the app was deleted or its secret replaced, or when the stored authorization is no longer valid.

What to do:

1. If you replaced the secret or created a new app at JTL, have the new client ID and secret ready.
2. Open Settings → Connections and select Reconnect on the account card.
3. Leave Client ID and Client secret blank to keep the stored app credentials, or enter the new values.
4. Select Reconnect with JTL and sign in with the same JTL account.
5. Select Test. When the card shows Working, open Fulfillment → Operations and retry the items under Failed. Retrying needs the Fulfillment operations permission.

For support: the details above, when the status first appeared, and whether the app was changed at JTL.

JTL or the network is unavailable

Code: unavailable

What you see: The hub shows JTL is not reachable right now. On an existing account, Test can end with Check failed and a similar message.

Likely cause: JTL’s service is down or under maintenance, or the connection between the hub and JTL timed out.

What to do:

1. Wait a few minutes. Nothing was changed, so trying again is safe.
2. Select Try again, or Test on an existing account.
3. If the problem lasts more than an hour, check whether you can open the FFN portal, then contact support.

For support: the details above and how long the problem has lasted.

Another error stopped the connection

Code: failed

What you see: The hub shows The connection could not be completed. This section also covers We could not confirm the connection, which appears when JTL reported success but the account is not listed in the workspace you have open.

Likely cause: JTL returned an unexpected answer, for example no account details, or an unexpected error occurred while saving. If the hub could not confirm the connection, the account may belong to a workspace that you cannot open with this login, or the connection list could not be loaded.

What to do:

1. If the screen offers Check again, select it.
2. Open Settings → Connections in the workspace where you started and check whether the account is listed.
3. If it is not, select Try again once.
4. If it fails again, contact support.

For support: the details above, with the exact time of each attempt so that support can find them.

Messages in the Connect JTL Fulfillment Network dialog

Some problems appear before you leave the hub:

• JTL connections are not available on this server yet. Balta Labs cannot offer a callback URL. Contact support.
• The JTL settings could not be loaded. Select Try again. If it keeps failing, contact support.
• The authorization could not be started. The reason appears below it, for example that the client ID and client secret are missing. A new connection needs both; when you reconnect, blank fields keep the stored app credentials.
• A reconnect stays in the account’s environment. You cannot switch between production and sandbox when reconnecting. For the other environment, add a new connection.