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

# Limits and credits

> Understand shared rate limits, credit consumption, quota periods, and how to handle HTTP 429 responses.

Your account's API keys share one rate-limit bucket, included credit allowance, and purchased credit balance.

## Plan allowances

| Plan | Requests per minute | Included credits per period | Active API keys |
| - | - | - | - |
| Free | 20 | 500 | 2 |
| Plus | 60 | 1,250 | Unlimited |

Read [Get usage](api-reference/get-usage) for your account's effective limits and reset time rather than hard-coding these values.

## Credit consumption

| Request | Credit cost |
| - | - |
| `GET /api/v1/companies?q=…` | 1 |
| `GET /api/v1/companies/{nif}` | 1 |
| `GET /api/v1/usage` | 0 |

Your credit is consumed when authentication and quota admission succeed, before the company handler validates input or retrieves data. You still consume a credit if the handler returns `400`, `404`, `500`, or `502`, or if a search returns no matches. Cached company lookups have the same credit cost.

Requests rejected for an invalid key, a rate limit, or an exhausted credit quota do not consume a credit. A credit-quota rejection can still consume rate-limit capacity because the rate check happens first.

You use your included credits first. After you exhaust them, company requests deduct from your purchased credit balance. The usage field `quotas.requests.used` counts both kinds of credit consumption, so it can exceed `quotas.requests.limit`.

### Quota periods

Your Free allowance resets at the start of each calendar month in UTC. Your effective Plus allowance uses your subscription billing period. Purchased credits are a separate balance; a quota-period reset does not replenish that balance.

Use `data.resetAt` from the usage response for the next included-credit reset. `data.period.start` and `data.period.end` are date-only labels for the current period; `resetAt` gives you the exact boundary.

## Request rate

Your rate limit uses a token bucket. The bucket holds up to your plan's requests-per-minute limit, and capacity refills continuously at that rate. It does not reset all at once at the next minute boundary.

Every admitted request, including usage checks and company requests that later fail, consumes one rate-limit token. Pace concurrent workers together because all keys on your account share the bucket.

### Response headers

Authenticated responses include these headers when admission succeeds or a quota/rate limit rejects your request:

| Header | Meaning |
| - | - |
| `RateLimit-Limit` | Your bucket capacity and refill rate in requests per minute. |
| `RateLimit-Remaining` | Whole tokens remaining after the admission attempt. |
| `RateLimit-Reset` | Unix timestamp in seconds when at least one token is available; near the current time if one is already available. This is not the time when the bucket becomes full. |
| `RateLimit-Policy` | Your policy in the form `20;w=60`, for example. |
| `Retry-After` | On `429`, seconds to wait before retrying. |

## Handle HTTP 429

Inspect the [problem response](errors) `type` to distinguish the two causes:

| Type suffix | Cause | What you should do |
| - | - | - |
| `rate-limit-exceeded` | No rate-limit token is available. | Wait at least `Retry-After` seconds, then retry at a lower request rate. |
| `monthly-quota-exceeded` | Your included allowance and purchased balance are exhausted. | Wait until the reset or add credits through your Nesu dashboard. |

For a credit-quota rejection, `Retry-After` points to the included allowance's reset. The problem also includes `quota: "monthly_credits"`, the included `limit`, and an RFC 3339 UTC `reset` timestamp.

You can still call [Get usage](api-reference/get-usage) when your credit allowance is exhausted, provided you have rate-limit capacity.


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