> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> This guide will help you diagnose and resolve common authentication and connection issues with the Qonto API.

## Step 1: Choose your authentication method

Before making any API calls, determine which authentication method you'll use:

* **[Static API Key](https://docs.qonto.com/guides/authentication/api-key.md)** - A login/secret pair provided by Qonto
* **[OAuth](https://docs.qonto.com/guides/authentication/oauth-flow.md)** - Token-based authentication using the OAuth 2.0 flow

> [!TIP]
>
> Not sure which to use? We have [a detailed guide here](https://docs.qonto.com/api-reference/business-api/introduction/authentication/methods.md#which-authentication-method-do-i-need) explaining the differences & supported endpoints for each authentication method.

## Step 2: Test with a simple endpoint

Make a test call to the [**List Bank Accounts**](https://docs.qonto.com/api-reference/business-api/organization-accounts/business-accounts/list.md) endpoint to verify your setup.

```bash theme={null}
GET /v2/bank_accounts
```

## Step 3: Diagnose the response

### ✅ Got a success response code? (2XX)

Expand the section below based on what you received:

> **✅ Received JSON Response**
>
> **Congratulations!** You're successfully authenticated and connected to the Qonto API.
>
> You can now proceed with making other API requests.

> **❌ Received HTML (OneLogin Page)**
>
> **Issue:** You're trying to access the Staging environment without proper Staging Token.
>
> **Solution:** Add the `X-Qonto-Staging-Token` header to your request. This token can be found in the developer portal.
>
> ```bash theme={null}
> X-Qonto-Staging-Token: your-staging-token-here
> ```
>
> > [!WARNING]
> >
> > The Sandbox environment requires the staging token header in addition to your regular authentication credentials.
>
> For the full picture — why the OneLogin page appears, and how to also bypass it from a browser when opening Sandbox URLs (e.g. an Onboarding `redirection_link` or an attachment URL) — see [Accessing the Sandbox environment](https://docs.qonto.com/guides/developer-portal/sandbox-access.md).

### ❌ Got an error response? (4XX)

Follow the troubleshooting steps for your authentication method:

**Static API Key**

#### Verify your API key format

Please follow [the documentation here](https://docs.qonto.com/guides/authentication/api-key.md) for static API key.

Your static API key must be provided in the `Authorization` header using HTTP Basic Authentication format:

```bash theme={null}
Authorization: {login}:{secret}
```

**Example:**

```bash theme={null}
Authorization: your-login-here:your-secret-here
```

> [!NOTE]
>
> Do not include "Basic" before the credentials - use the raw `{login}:{secret}` format directly.\
> Some users confuse this with basic authentication, but it is not.

#### Common mistakes

* Missing the colon separator: `loginSecret`
* Swapping login and secret: `{secret}:{login}`
* Adding a "Bearer" prefix before the login & secret
* Adding a "Basic" prefix before the login & secret
* Including extra spaces or line breaks
* Base64 encoding when not required

**OAuth**

#### Verify your access token format

Please follow [the documentation here](https://docs.qonto.com/guides/authentication/oauth-flow.md) for OAuth access.

Your OAuth access token must be provided in the `Authorization` header with the `Bearer` scheme:

```bash theme={null}
Authorization: Bearer {accessToken}
```

**Example:**

```bash theme={null}
Authorization: Bearer eyJhbGciOi...
```

> [!WARNING]
>
> The keyword "Bearer" must be included, followed by a space, then your access token.

#### Common Mistakes

* Missing "Bearer" prefix
* Using an expired access token
* Including extra characters or line breaks
* Using the refresh token instead of the access token

> [!TIP]
>
> Access tokens typically expire after a set period. If you're getting authentication errors, try refreshing your token.

## Still stuck? Contact Qonto support

If you are unable to resolve the issue, reach out to the Qonto team. To help us investigate as quickly as possible, include a trace identifier from the failing response. You can use either of the following—they always match on error responses:

* The **`X-Tyk-Trace-Id`** response header (present on every API response):

```
X-Tyk-Trace-Id: 6f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c
```

* The **`trace_id`** field in the JSON body (always included on error responses):

```json theme={null}
{
  "errors": [ ... ],
  "trace_id": "6f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c"
}
```

> [!TIP]
>
> Error responses always include `trace_id` in the JSON body, and every API response includes an `X-Tyk-Trace-Id` header. Copy either value and attach it to your support request—they identify the same request and speed up troubleshooting significantly.