> ## 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](/get-started/business-api/authentication/api-key)** - A login/secret pair provided by Qonto
* **[OAuth](/get-started/business-api/authentication/oauth/oauth-flow)** - Token-based authentication using the OAuth 2.0 flow

<Tip>
  Not sure which to use? We have [a detailed guide here](/get-started/business-api/authentication/introduction#which-authentication-method-do-i-need) explaining the differences & supported endpoints for each authentication method.
</Tip>

## Step 2: Test with a simple endpoint

Make a test call to the [**List Bank Accounts**](/api-reference/business-api/accounts-organizations/business-accounts/list) 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:

<AccordionGroup>
  <Accordion title="✅ Received JSON Response">
    **Congratulations!** You're successfully authenticated and connected to the Qonto API.

    You can now proceed with making other API requests.
  </Accordion>

  <Accordion title="❌ 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.
    </Warning>

    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](/get-started/general/sandbox-access).
  </Accordion>
</AccordionGroup>

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

Follow the troubleshooting steps for your authentication method:

<Tabs>
  <Tab title="Static API Key">
    #### Verify your API key format

    Please follow [the documentation here](/get-started/business-api/authentication/api-key) 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.
    </Note>

    #### 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
  </Tab>

  <Tab title="OAuth">
    #### Verify your access token format

    Please follow [the documentation here](/get-started/business-api/authentication/oauth/oauth-flow) 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.
    </Warning>

    #### 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.
    </Tip>
  </Tab>
</Tabs>

## 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.
</Tip>