> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mixlayer.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mixlayer.com/_mcp/server.

# Credits & Limits

> Understand Mixlayer credit balances, automatic top-ups, and RPM and TPM rate limits

Mixlayer applies billing and rate limits independently. A request can have
enough rate-limit capacity but fail because the billing account has no credit,
or have sufficient credit but be rate limited.

## Credit-based billing

Billing accounts can operate in **prepaid** or **post-paid** mode. Credit-based
billing, including recharges and automatic top-up, applies only to prepaid
accounts. Paid model usage on a prepaid account draws from the credit balance
attached to your organization's billing account. Free models do not require
prepaid credit.

To switch to post-paid billing, [contact us](mailto:hello@mixlayer.com).

You can review the balance, add a payment method, and purchase more credit from
the [Mixlayer console](https://console.mixlayer.com/app/billing). A recharge is
processed against the billing account's saved payment method.

When a paid model cannot run because the balance is empty, Mixlayer returns
HTTP `402` with an OpenAI-compatible billing error:

```json
{
  "error": {
    "message": "Prepaid credits are required to use this model.",
    "type": "billing_error",
    "code": "insufficient_prepaid_credits"
  }
}
```

Do not retry this response with backoff. Add credit or fix the payment method,
then retry after the balance is available.

The [Platform API](/api-reference/platform-api/platform-api) also exposes
billing-account details, recharge history, manual recharges, and automatic
top-up controls.

### Automatic top-up

Automatic top-up helps prevent an active workload from exhausting its prepaid
balance. It has two settings:

| Setting            | Behavior                                                   |
| ------------------ | ---------------------------------------------------------- |
| **Threshold**      | The credit balance that triggers a top-up.                 |
| **Target balance** | The balance Mixlayer attempts to restore after the top-up. |

The target is a balance, not a fixed purchase amount. For example, if the
balance falls below the threshold, Mixlayer charges the saved payment method
for enough credit to move the balance toward the configured target.

Set the threshold high enough to cover normal usage while a payment is being
processed. Automatic top-up depends on the saved payment method succeeding
and should not be treated as instantaneous.

## Platform rate limits

Rate limits protect shared platform capacity and help keep inference responsive
during changes in demand. They apply per organization and per model, and may
change based on available platform capacity.

Mixlayer limits generation traffic using two independent capacities:

* **Requests per minute (RPM)** controls the rate at which generation requests
  are admitted.
* **Tokens per minute (TPM)** limits the combined input (cached and non-cached)
  and output token throughput across those requests.

Both capacities refill continuously rather than resetting at a fixed
wall-clock minute. Limits are evaluated for the organization and model. A
model-specific policy can override the organization's general policy.

Before generation starts, Mixlayer reserves a conservative TPM estimate that
accounts for the input and requested output budget. After generation completes,
the reservation is reconciled against actual token usage. A request is rejected
when either the RPM or TPM bucket does not have enough capacity.

Mixlayer does not publish fixed limit values because limits can differ by
organization and model. Use the response headers below to observe the limits
applied to a request. If your workload needs more capacity, [contact us](mailto:hello@mixlayer.com) to discuss custom limits.

### Response headers

When rate limiting is active, metered generation responses include:

| Header                           | Description                                                                             |
| -------------------------------- | --------------------------------------------------------------------------------------- |
| `x-ratelimit-limit-requests`     | RPM capacity applied to the request.                                                    |
| `x-ratelimit-remaining-requests` | Request capacity remaining after the rate-limit decision.                               |
| `x-ratelimit-reset-requests`     | UTC RFC 3339 timestamp when the request capacity is expected to be fully restored.      |
| `x-ratelimit-limit-tokens`       | TPM capacity applied to the request.                                                    |
| `x-ratelimit-remaining-tokens`   | Token capacity remaining after the initial reservation.                                 |
| `x-ratelimit-reset-tokens`       | UTC RFC 3339 timestamp when the token capacity is expected to be fully restored.        |
| `retry-after`                    | Seconds to wait before retrying a rejected request. Successful requests may return `0`. |

When a limit is exceeded, Mixlayer returns HTTP `429`:

```json
{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded"
  }
}
```

### Working within rate limits

* Pace traffic instead of sending large bursts.
* Set output-token limits close to what the request actually needs. Very large
  output budgets require a larger initial TPM reservation.
* Use the remaining-capacity headers for observability, but do not treat them
  as a reservation. Other concurrent requests may consume capacity before the
  next request starts.
* On HTTP `429`, wait for at least the duration in `retry-after`.
* If `retry-after` is unavailable, use exponential backoff with jitter. Cap the
  delay and the number of attempts so callers do not retry indefinitely.
* Retry transient `429` and `5xx` responses only. Do not retry authentication,
  validation, permission, or billing errors without first correcting their
  cause.