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

# Rate limits

> Understand RPM, TPM, and spending limits in ScitiX Model Inference, configure API key limits, and handle 429 responses with bounded retries.

Rate limits control the request and token throughput of model APIs. When a call returns HTTP `429`, check the error type and retry hints before sending another request.

## Understand rate limits

API keys support RPM and TPM limits. These limits serve different purposes from spending quotas:

| Setting | Meaning | Purpose |
| - | - | - |
| RPM limit | Maximum requests per minute. | Control how quickly requests are sent. |
| TPM limit | Maximum tokens per minute. | Control token throughput. |
| Spending quota | Maximum spending over a period or the lifetime of a key. | Control costs, not request rates. |

Monitor RPM and TPM separately. A small number of requests can still consume many tokens when contexts or outputs are long. An available spending balance does not prevent rate limiting.

**Concurrency is not RPM.** Concurrency is the number of requests in progress at the same time; RPM measures how quickly requests are sent. Even sequential calls can trigger a rate limit if each new request starts as soon as the previous one finishes.

## View and configure limits

Open [API Keys](https://console.scitix.ai/model-inference/api_keys) in the console and click **Edit** for the key. Check or update **RPM Limit** and **TPM Limit**. For key creation, spending quotas, and other key management tasks, see [Manage API keys](https://docs.scitix.ai/model-inference/usage/api-keys.md).

Leaving an RPM or TPM field empty, or setting it to `0`, means that no custom limit is set for that field.

> [!NOTE]
>
> Removing a custom key limit does not remove every service limit or guarantee that requests will never return `429`. Use the actual response to identify the cause, rather than relying only on the key configuration.

## Identify a rate-limit response

Check the HTTP status first, followed by `error.type` and, when present, `error.code`.

| HTTP status | `error.type` | `error.code` | Action |
| - | - | - | - |
| `429` | `rate_limit_error` | `rate_limit_exceeded` | Read the error and retry hints, then reduce the request rate before trying again. |

Keep the original error type and code. Use them together with the HTTP status and message; not every failure is a rate-limit error. HTTP `402` indicates a billing rejection, so check your balance or spending quota. For HTTP `401`, `400`, or `422`, fix authentication or the request first. See [Error handling](https://docs.scitix.ai/model-inference/api/error-handling.md) for the full classification.

### Response example

The following example shows an RPM rejection for a non-streaming Chat Completions request. The limit of `1` is illustrative, not the platform's default RPM. Request identifiers have been replaced with placeholders.

Selected response headers:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Retry-After: 60
request-id: REQUEST_ID
x-request-id: REQUEST_ID
x-ratelimit-limit-requests: 1
x-ratelimit-remaining-requests: 0
x-ratelimit-reset-requests: 60
```

Response body:

```json theme={null}
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: limit is 1 requests per minute (request_id: REQUEST_ID)",
    "msg": "Rate limit exceeded: limit is 1 requests per minute",
    "request_id": "REQUEST_ID",
    "traceId": "TRACE_ID",
    "retry_after_sec": 60
  }
}
```

| Field or header | Purpose |
| - | - |
| `error.message` / `error.msg` | Error description. Check whether it identifies a request-rate or token-rate limit. |
| `error.retry_after_sec` / `Retry-After` | Retry hints, both expressed in seconds in this example. When present, read the actual value and wait at least that long. Do not hard-code the example value of `60`. |
| `error.request_id` | Request ID for support investigations. |
| `error.traceId` | Trace ID, distinct from the request ID. Retain it when present. |

Responses may also include the `x-ratelimit-*` request-limit headers shown above. Keep their original values for troubleshooting, but do not treat them as a guarantee that the next request will succeed or substitute `x-ratelimit-reset-requests` for an explicit retry hint.

Fields and headers vary by error. Clients must handle missing optional fields rather than requiring every protocol or every `429` response to match this example.

### Inspect a single request

This curl example disables automatic retries so that you can inspect one request's HTTP status, headers, and body. Set `API_KEY` to an existing key first. Do not put keys in source code or logs.

```bash theme={null}
curl --include --silent --show-error --max-time 30 \
  'https://api.scitix.ai/model-api/chat/completions' \
  --header "Authorization: Bearer ${API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "Qwen/Qwen3.6-27B",
    "messages": [{"role": "user", "content": "Reply with OK."}],
    "stream": false,
    "max_completion_tokens": 64
  }'
```

Replace `model` with an available model ID as needed. This example is for inspecting a response, not for repeatedly sending requests to trigger a limit. A successful request can incur charges. HTTP `200` alone does not establish that generation finished normally: also check the content and the protocol's completion status.

## Wait and retry within bounds

> [!WARNING]
>
> A retry hint does not guarantee recovery. The next request can still return `429` after you wait. Set a retry budget, and do not rotate API keys to bypass limits.

Handle an explicit rate-limit error in this order:

1. **Record the error.**
   Keep the HTTP status, error type, error code, request ID, and retry hints.
2. **Check the retry budget.**
   Set a maximum number of attempts, a cumulative wait limit, and a timeout for the entire operation. Count the initial request as an attempt.
3. **Calculate the wait.**
   Wait at least the number of seconds in `error.retry_after_sec`, when present. Also read a parseable `Retry-After` header. If neither provides a usable hint, apply your application's exponential backoff and jitter instead of retrying immediately.
4. **Wait, then try again.**
   Read the new response's hints rather than reusing the previous wait value. Further `429` responses remain subject to the same budget.
5. **Stop at the limit.**
   Let the application handle the failure, for example by asking the user to try later or pausing a batch. Contact support if failures persist.

If two parseable retry hints disagree, the client can conservatively use the longer wait or stop automatic retries to investigate. This is a client policy, not a server-defined precedence rule. If the wait exceeds the remaining budget, stop rather than shortening the wait and retrying early.

The following is **pseudocode, not executable code**. A maximum of three attempts and 120 seconds of cumulative waiting is only an example client budget, not a platform limit or recovery promise. Set the overall operation timeout separately to suit your application.

```text theme={null}
Set the attempt limit, cumulative wait limit, and operation timeout
cumulative_wait = 0

For each permitted attempt:
    Send one request with a timeout no longer than the remaining operation time
    If the response is successful:
        Check its content and completion status, return the result, and stop
    If the response is not an explicit 429 rate-limit error:
        Hand it to the appropriate error handler and stop this retry loop
    If the attempt limit or operation timeout has been reached:
        Return failure and stop
    Read retry hints from this response; otherwise use backoff
    If the wait would exceed the cumulative limit or exhaust the remaining time:
        Return failure and stop
    Wait for the calculated duration and add it to cumulative_wait

Return failure, retaining the last error and request identifiers
```

Check whether your SDK, HTTP client, or application already retries requests. Avoid stacking retries across layers. A network timeout or disconnected connection does not prove that a request was never processed; let the application decide whether resending is appropriate instead of applying the `429` loop automatically.

### Retry boundaries for streaming

For a request that explicitly returns `429` before any output begins, use the strategy above to decide whether to retry. Do not automatically replay a request after receiving partial output: doing so can duplicate content or incur additional charges.

For streaming calls, check in-stream errors and completion events as well as the initial HTTP status. Follow the event format for the selected protocol; the non-streaming JSON example is not a universal format for streaming errors.

## Control traffic and observe changes

Backoff handles failed requests; it does not replace traffic control during normal operation.

* **Smooth request traffic.** Queue batch work instead of sending a whole batch at once.
* **Limit concurrency.** Bound in-flight requests and separately control the rate at which requests start. Lower concurrency alone may not prevent RPM limiting.
* **Manage token usage.** Remove unnecessary repeated context and set an output budget that fits the task. Do not treat billable tokens or a response's `usage` as the remaining live TPM allowance.
* **Prevent retry amplification.** Apply the same client-side traffic controls to initial requests and retries.

Use [Metrics](https://console.scitix.ai/model-inference/metrics) to observe call trends, average RPM, and average TPM. Use [Usage Detail](https://console.scitix.ai/model-inference/usage_detail) for individual requests.

Aggregate metrics describe the selected time range. They do not show a live remaining allowance or guarantee acceptance of the next request. Check client logs, actual errors, and key settings together. See [View metrics](https://docs.scitix.ai/model-inference/usage/view-metrics.md) and [View usage](https://docs.scitix.ai/model-inference/usage/view-usage.md).

## Investigate persistent rate limiting

Check the key in use, its RPM/TPM settings, request timing, and automatic retries in your client and SDK. If `429` continues after the indicated waits, stop repeatedly trying and provide support with:

* Request time and time zone.
* Model ID, endpoint path, and whether the request used streaming.
* HTTP status, `error.type`, `error.code` when present, and error message.
* Request ID and `traceId` when present.
* Current and previous retry hints, actual wait durations, and attempt count.
* Original `x-ratelimit-*` headers when present.
* The key's RPM/TPM configuration and client traffic pattern.

Do not share the API key or the full `Authorization` header. Redact business data in request bodies, logs, and screenshots.

## FAQ

> [accordion] Why can requests return 429 when RPM or TPM is set to 0?
>
> `0` removes the custom limit for that field, not the other limit or every service limit. For example, if TPM is `0`, still check RPM. Identify the limiting factor from the actual error rather than the setting alone.

> [accordion] Why am I still rate-limited after waiting for Retry-After?
>
> A retry hint does not guarantee acceptance. Read the latest error and wait value, and check request timing and stacked retries. Stop automatic retries when the budget is exhausted or failures persist, then contact support with the request identifiers.

> [accordion] Does a per-minute limit reset at the next clock minute?
>
> Do not infer a reset at a clock-minute boundary from "per minute" or an example value of `60`. Read the actual retry hint instead of fixing the recovery time at 60 seconds, and handle failures that persist after waiting.

> [accordion] Why do I get 429 when average RPM is below my limit?
>
> The console's average RPM is aggregated over the selected time range, not the state at each request's start. Read the error to distinguish request-rate limits from token-rate limits, and inspect finer-grained client timestamps rather than comparing averages alone.

> [accordion] Can I calculate TPM directly from usage.total\_tokens?
>
> Do not treat a response's `usage.total_tokens` as a rate-limit counter or a live remaining TPM allowance. Usage describes that request's consumption. Cache, reasoning, and other tokens follow protocol-specific counting rules; billing usage alone does not establish the TPM counting rule.

> [accordion] Will a higher spending quota, a top-up, or more keys resolve 429?
>
> Spending quotas, account balance, and rate limits are separate. For `402`, investigate billing. For `429`, investigate the actual limit and request traffic. Raising a spending quota does not raise throughput, and adding or rotating keys must not be used to bypass limits.

> [accordion] Are 429 requests billed, and can I retry immediately if they are not?
>
> Rate-limit rejections with `429` are not billed; see [Token usage and billing](https://docs.scitix.ai/model-inference/usage/billing.md). Billing and rate-limit counting are separate questions. An unbilled rejection is not a reason to retry repeatedly without waiting. Follow retry hints and your retry budget.

## Related guides

* [Manage API keys](https://docs.scitix.ai/model-inference/usage/api-keys.md): Manage keys, spending quotas, and custom rate limits.
* [Error handling](https://docs.scitix.ai/model-inference/api/error-handling.md): Find other error types and recommended actions.
* [Token usage and billing](https://docs.scitix.ai/model-inference/usage/billing.md): Understand token types, pricing, and charges for failed requests.
* [View metrics](https://docs.scitix.ai/model-inference/usage/view-metrics.md): Observe aggregate call trends.
* [View usage](https://docs.scitix.ai/model-inference/usage/view-usage.md): Inspect individual requests' usage and timing.


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