> ## Documentation Index
> Fetch the complete documentation index at: https://pioneer-kelton-add-decoder-inference-prices.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits and credit / spending caps for the Pioneer API

> Per-endpoint request-rate limits, edge WAF quotas, monthly credit and overage spending caps, 429 handling, and how to request higher limits on the Pioneer API.

## Request-rate quotas and credit / spending caps for the Pioneer API, how to handle 429 errors, and how to request higher limits

The Pioneer API enforces two independent things that can stop a request: **request-rate limits** that cap how many API calls you can make per minute or hour, and **credit-based usage limits** that cap how much you can spend. Exceeding a request-rate limit returns `429 Too Many Requests`. Running out of credits or hitting your plan's overage ceiling returns `402 Payment Required` or `403 Forbidden` instead — see [Credit limits and overage spending cap](#credit-limits-and-overage-spending-cap) below.

## Request-rate limits

Two independent layers protect the API:

1. **Edge rate limit** — always applied to every request at the load balancer, before it reaches the API, regardless of endpoint or authentication. Aggregated by the IP address the edge observes, which is not always your application's true client IP (for example, requests proxied through a shared egress hop are aggregated together). Limit: 100,000 requests / 60 seconds.
2. **Per-endpoint limit** — most endpoints below enforce their own limit scoped to your billing team (falling back to API key, then user, then client IP for unauthenticated requests). This is the limit that governs a normal, authenticated caller. It replaces the generic per-IP default for that endpoint rather than stacking on top of it — the per-IP default only governs endpoints with no listed override.

| Endpoint                                                                        | Scope         | Limit                           |
| ------------------------------------------------------------------------------- | ------------- | ------------------------------- |
| All other endpoints (no endpoint-specific limit set)                            | Per client IP | 20,000 / min · 1,000,000 / hour |
| `POST /inference`                                                               | Per user      | 5,000 / min                     |
| `POST /v1/chat/completions`, `/v1/completions`, `/v1/responses`, `/v1/messages` | Per user      | 5,000 / min                     |
| `POST /gliner-2/*`                                                              | Per user      | 15,000 / min                    |
| `POST /generate/*`                                                              | Per user      | 120 / min                       |
| `POST /felix/training-jobs`                                                     | Per user      | 20 / min                        |

For a single API key or team, the per-endpoint limit above is what actually binds. The 100,000 requests / 60 second edge limit is a separate, always-on ceiling shared by all traffic through the same load balancer — it only comes into play when many different callers share the same observed IP and collectively exceed it.

## Credit limits and overage spending cap

Inference is billed against a credit balance rather than a request-rate window (1 credit = \$0.01). Each plan includes a credit allowance — the Free plan grants a one-time allowance that does not renew, while paid plans renew their included credits every billing month. Once a paid plan's included credits are used, additional usage draws from overage billing (if enabled) up to that plan's maximum overage spend per month; on the Free plan, running out simply stops inference until you add credits or upgrade.

Exceeding a credit limit does **not** return `429 Too Many Requests`. Instead it returns:

* `402 Payment Required` when your included credits are exhausted and there's no spendable balance to draw from (`code: "out_of_credits"`).
* `403 Forbidden` when your plan's maximum monthly overage spend has been reached (`code: "credit_ceiling_reached"`).

Both responses share the same JSON shape:

```json theme={null}
{
  "code": "out_of_credits",
  "message": "You've used your included credits. Add credits or enable auto top-up.",
  "resolution_url": "https://agent.pioneer.ai/credits"
}
```

You can check your current usage, remaining allowance, and overage settings anytime in the billing section of the dashboard.

Credit limits, overage ceilings, and plan terms are subject to availability and may be adjusted over time.

<Tip>
  Need a higher limit? Reach out to [support@fastino.ai](mailto:support@fastino.ai) or your account contact and we can raise the ceiling on a custom plan.
</Tip>

## Handling 429 responses

When you exceed a limit, the API returns `429 Too Many Requests` and includes a `Retry-After` header that tells you how many seconds to wait before retrying.

```bash cURL theme={null}
HTTP/2 429
retry-after: 3
content-type: application/json

{
  "detail": "Rate limit exceeded: ..."
}
```

The following pattern handles `429` responses with a simple sleep-and-retry loop:

```python Python theme={null}
import time
import requests

def call_with_retry(url, headers, payload, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=payload)

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 1))
            print(f"Rate limited. Retrying in {retry_after}s...")
            time.sleep(retry_after)
            continue

        response.raise_for_status()
        return response.json()

    raise RuntimeError("Max retries exceeded.")
```

<Note>
  Credit and overage denials (`402`/`403`, see [Credit limits and overage spending cap](#credit-limits-and-overage-spending-cap)) won't resolve by waiting — the retry loop above only applies to `429` responses. A `402`/`403` needs a billing action (add credits, enable auto top-up, or upgrade your plan) before the next request can succeed.
</Note>

## Requesting higher limits

If the default or Pro-tier limits don't fit your workload, contact the Pioneer team to discuss a custom plan.

[Request higher limits](https://forms.gle/uzRf8bM2yZtpJFmd7)