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

# Limits

> Rate limit, daily quota, request weights, concurrency and pagination caps of the free plan.

Gabin is free during the preview. Limits keep the service fast for everyone and protect the data from bulk scraping. They apply per **account**: all your keys and OAuth tokens share them, and MCP tool calls count like API calls.

## Free plan

| Limit | Value | When exceeded |
| - | - | - |
| Rate | 60 units per minute | `429 RATE_LIMITED` with `Retry-After` |
| Daily quota | 5,000 units per UTC day | `429 QUOTA_EXCEEDED` |
| Concurrent requests | 2 at a time per account | `429 RATE_LIMITED` with `Retry-After: 1` |
| Page size | 100 items | — |
| Results reachable per query | 10,000 (cursor pagination) | `400 PAGINATION_LIMIT` |
| Active API keys | 5 per account | — |

An IP address and its network also have a daily ceiling across all accounts (20,000 units per IP address, 60,000 per /24 IPv4 or /48 IPv6 network). You only reach it by spreading load over many accounts; the error is `429 QUOTA_EXCEEDED` and its message says "this IP address" or "this network".

Higher limits are not available yet during the preview.

## Request weights

A request costs 1 unit unless its endpoint says otherwise. The weight counts against both the rate and the quota.

| Request | Units |
| - | - |
| Most endpoints | 1 |
| Advanced search: `POST /v1/search`, `POST /v1/search/count` | 5 |
| Map tile served from cache | 0.1 |
| Map tile computed from the database | 0.5 |

The weight is listed in the description of each endpoint in the API reference. A request refused with `RATE_LIMITED` or `BUSY` because of concurrency costs nothing.

## Response headers

Every `/v1` response carries:

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | Units allowed per minute |
| `X-RateLimit-Remaining` | Units left in the current minute |
| `X-RateLimit-Reset` | Seconds until the minute window resets |
| `X-Quota-Remaining` | Units left today (UTC) |
| `X-Request-Id` | Identifier of the request, to quote if you report a problem |
| `Retry-After` | On `429` and `503`: seconds to wait before retrying |

`GET /v1/me` returns the same counters as JSON, with today's usage.

## Handling limits in your code

* Send requests **one or two at a time** per account. A third concurrent request is refused immediately.
* On `429` or `503`, wait `Retry-After` seconds, then retry. Back off exponentially if it happens again.
* Do not retry `QUOTA_EXCEEDED` before the next UTC day.
* Cache what you read: company and building data change at most daily.

```javascript theme={null}
async function gabin(path, { retries = 3 } = {}) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(`https://api.gabin.ai/v1${path}`, {
      headers: { Authorization: `Bearer ${process.env.GABIN_API_KEY}` },
    });
    if (res.ok) return res.json();
    const body = await res.json().catch(() => null);
    const code = body?.error?.code;
    const retriable = res.status === 503 || (res.status === 429 && code !== "QUOTA_EXCEEDED");
    if (!retriable || attempt >= retries) throw new Error(`${res.status} ${code}: ${body?.error?.message}`);
    const wait = Number(res.headers.get("retry-after")) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
}
```

The [MCP server](https://docs.gabin.ai/mcp/overview.md) already queues its own calls to stay within the concurrency limit.


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