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

# Rate limits & quotas

> Free-tier usage quota and per-minute rate limits for the Instant Classification API.

The Instant Classification API enforces two types of limit: a **usage quota** for free-tier accounts and a **per-minute rate limit** for all accounts.

## Free-tier quota

New accounts start on the free tier. Free-tier accounts are limited to **20 classification requests** in total. When your quota is exhausted, the API returns `402`:

```json theme={null}
{
  "detail": "Usage quota exceeded. Contact support for elevated access."
}
```

The free tier does not reset — it is designed for evaluation. To continue using the API, contact [support@thedatacity.com](mailto:support@thedatacity.com) for a paid plan.

Only **successful** classifications count against the quota. Requests that fail with `4xx` or `5xx` are recorded but don't consume it, so a run of errors won't burn through your allowance.

<Note>
  The free tier gives you 20 requests to evaluate the API. If you're building an integration, contact support for a paid account before you start development.
</Note>

## Per-minute rate limit

Free and paid accounts alike are limited to **5 requests per minute**, counted per authenticated user. Requests without a valid token are counted per IP address instead.

When you exceed the limit, the API returns `429` with an `error` key rather than the usual `detail`:

```json theme={null}
{
  "error": "Rate limit exceeded: 5 per 1 minute"
}
```

Every classification request counts, regardless of response status or payload size.

<Note>
  No `Retry-After` or `X-RateLimit-*` headers are sent, so you can't read the reset time from the response. Use the backoff schedule below.
</Note>

### The login endpoints are limited too

`POST /api/v1/login/access-token` and `POST /api/v1/password-recovery/{email}` are also limited to **5 requests per minute** in production. Tokens last 8 days, so fetch one and cache it rather than requesting a token per call.

## How the two limits interact

| Account type | Usage quota                      | Per-minute rate limit |
| ------------ | -------------------------------- | --------------------- |
| Free         | 20 successful requests, lifetime | 5 requests/minute     |
| Paid         | Unlimited                        | 5 requests/minute     |

If a free-tier account sends requests rapidly, the per-minute rate limit may reject a request before the quota check runs.

## Backing off

Retry `429` responses with exponential backoff:

```text theme={null}
attempt 1 → wait 2 s
attempt 2 → wait 4 s
attempt 3 → wait 8 s
attempt 4 → give up, surface the error
```

Add random jitter (0–500 ms) to prevent thundering-herd retries.

<Warning>
  Do **not** retry `402` (quota exceeded). The request will fail the same way until your account is upgraded to a paid plan.
</Warning>

## Checking your limits

Call `GET /api/v1/utils/public-config` to see the current free quota:

```bash theme={null}
curl -sS "https://instant-classification-api.thedatacity.com/api/v1/utils/public-config"
```

```json theme={null}
{
  "free_quota_limit": 20,
  "free_quota_scope": "lifetime"
}
```

This endpoint is unauthenticated, and it reports the limit rather than your personal usage. To check whether the quota still applies to you, call [`/api/v1/login/test-token`](/instant-classification/guides/authentication) and read `is_paid`. To track consumption, count your own successful responses.

To upgrade to a paid account, contact [support@thedatacity.com](mailto:support@thedatacity.com).

<Snippet file="need-help.mdx" />