Rate limits & quotas - The Data City

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:

{
  "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 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.

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.

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:

{
  "error": "Rate limit exceeded: 5 per 1 minute"
}

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

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.

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:

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.

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

Checking your limits

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

curl -sS "https://instant-classification-api.thedatacity.com/api/v1/utils/public-config"

{
  "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 and read is_paid. To track consumption, count your own successful responses. To upgrade to a paid account, contact support@thedatacity.com.

​Free-tier quota

​Per-minute rate limit

​The login endpoints are limited too

​How the two limits interact

​Backing off

​Checking your limits

Free-tier quota

Per-minute rate limit

The login endpoints are limited too

How the two limits interact

Backing off

Checking your limits