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

# Errors

> Error format and the list of Gabin API error codes, with their HTTP status and what to do.

An error response has an HTTP status from 400 to 599 and this body:

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "No building with id bdnb-bg-XXXX.",
    "docs_url": "https://docs.gabin.ai/errors#not_found"
  }
}
```

* `code` is stable: test it in your code.
* `message` is written for a developer or an AI assistant and can change. It says what was wrong and, when possible, how to fix it.
* `docs_url` points to the section of this page for the code.

Quote the `X-Request-Id` response header if you report a problem.

| Code | Status | Retry? |
| - | - | - |
| [`UNAUTHENTICATED`](#unauthenticated) | 401 | No, fix the token |
| [`FORBIDDEN`](#forbidden) | 403 | No |
| [`NOT_FOUND`](#not_found) | 404 | No |
| [`INVALID`](#invalid) | 400 | No, fix the request |
| [`ZONE_REQUIRED`](#zone_required) | 400 | No, add or narrow a zone |
| [`PAGINATION_LIMIT`](#pagination_limit) | 400 | No, narrow the query |
| [`RATE_LIMITED`](#rate_limited) | 429 | Yes, after `Retry-After` |
| [`QUOTA_EXCEEDED`](#quota_exceeded) | 429 | Next UTC day |
| [`TIMEOUT`](#timeout) | 503 | Yes, or narrow the query |
| [`BUSY`](#busy) | 503 | Yes, after `Retry-After` |
| [`INTERNAL`](#internal) | 500 | Yes, later |

## UNAUTHENTICATED

**401.** The `Authorization: Bearer` header is missing, or the token is unknown, revoked or expired. Check that the header is present and that the key starts with `gab_live_`. Create a key at [gabin.ai/compte/api](https://gabin.ai/compte/api). An OAuth access token (`gat_…`) expires after one hour: your MCP client refreshes it, or asks you to sign in again. See [authentication](https://docs.gabin.ai/authentication.md).

## FORBIDDEN

**403.** The token is valid but cannot perform this action. No current endpoint returns it; it is reserved for actions outside your plan.

## NOT\_FOUND

**404.** No resource with this identifier, or no route at this path. Check the identifier format in [conventions](https://docs.gabin.ai/conventions.md#identifiers). A company under SIRENE partial diffusion has no building and no position: related lookups return nothing.

## INVALID

**400.** A parameter is missing, malformed or out of range, or a cursor was altered or reused on another endpoint. The message names the parameter and the expected value. Parameter rules are in the API reference.

## ZONE\_REQUIRED

**400.** The query is too broad to answer quickly: for example an activity filter with no zone, or an advanced search over all of France or a whole department for companies. Add a zone (city, district, `bbox`, radius) or narrow the one you have. See [advanced search](https://docs.gabin.ai/guides/advanced-search.md).

## PAGINATION\_LIMIT

**400.** You paged beyond the 10,000 results reachable for one query, or beyond the cap of an endpoint (for example the companies linked to one building). Narrow the query with filters or a smaller zone. See [conventions](https://docs.gabin.ai/conventions.md#pagination).

## RATE\_LIMITED

**429.** Too many units in the current minute, or more than 2 concurrent requests for your account. Wait the number of seconds in `Retry-After`, then retry. Send requests one or two at a time. See [limits](https://docs.gabin.ai/limits.md).

## QUOTA\_EXCEEDED

**429.** The daily quota of your account (5,000 units per UTC day) is used up, or, if the message says so, the daily ceiling of your IP address or network. It resets at midnight UTC. `GET /v1/me` shows the remaining quota. See [limits](https://docs.gabin.ai/limits.md).

## TIMEOUT

**503.** The query took too long and was stopped. It usually means the zone or the filters match too much data. Retry once, then narrow the query.

## BUSY

**503.** Too many requests are reading the database at this moment across the API. Wait `Retry-After` seconds (usually 1) and retry. The request did not count against your quota.

## INTERNAL

**500.** An unexpected error on our side. Retry later; if it persists, report it with the `X-Request-Id`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.