# BYOK fees and credentials

Source: https://platform.lyrouter.com/ai_gateway/docs/byok-cost/en
Last updated: 2026-10-22

BYOK involves two charges: the provider bills your account for upstream usage, and LYRouter deducts a fixed service fee from your Credits balance for each successful BYOK call; the amount actually deducted appears in Consumption. The BYOK list tracks estimated provider cost and token usage per credential, and replacing, enabling or disabling, reordering and limiting credentials all happen in the Credentials step of the BYOK editor.

## Cost breakdown

| Charge | Charged by | Where to see it |
| --- | --- | --- |
| Upstream token cost (Token-based) | The provider | The provider's bill; LYRouter's estimate is in the BYOK list and in BYOK token cost in [usage analytics](https://platform.lyrouter.com/ai_gateway/docs/analytics/en) |
| Coding Plan subscription fee (Subscription) | The provider | BYOK subscription cost in usage analytics, converted from the amount entered in BYOK |
| Platform service fee | LYRouter, deducted from your Credits balance | Consumption in **Subscription & Credits** |

## Platform service fee

- **When it is charged**: when a request is finally completed by a BYOK credential. Failed BYOK calls are free; when BYOK fails and a platform credential completes the request, the platform price is charged and no service fee is.
- **Scope**: it applies to both Token-based and Subscription billing, and to built-in and custom providers alike.
- **Balance requirement**: before sending the first BYOK request, the gateway reserves this service fee from your balance. If the balance cannot cover it, the gateway returns 402 `insufficient credit balance` (`error.code` `insufficient_credit_balance`); the request is not sent to the provider and does not switch to a platform source. If the account has never been topped up, `error.code` is `balance_missing`. Top up on the **Subscription & Credits** page to recover.
- **Expired subscription**: once the account's subscription has expired and the grace period has passed, every call, BYOK included, returns 402 `subscription expired; renew to continue`; see [Unavailable models](https://platform.lyrouter.com/ai_gateway/docs/unavailable/en).

## Usage and cost in the BYOK list

| Where | What it shows |
| --- | --- |
| Cumulative cost and Cumulative tokens cards | Cumulative totals for all BYOK credentials |
| Provider channel row | Total cost and Total tokens are the sums over all of the channel's credentials; Monthly cost and Monthly tokens show "—", and the note "Monthly statistics pending" appears next to the cards |
| Credential row | Monthly cost, Total cost, Monthly tokens and Total tokens show "used / limit" with a percentage, or "Unlimited" when no limit is set |

- **How cost is calculated**: provider cost is estimated from the list price × discount set in Models & cost and the four token types Input (cache miss), Input (cache hit), Output and Explicit cache write. It excludes the platform service fee and subscription fees. The token count is the sum of the four types.
- **"Statistics pending"**: the credential has no calls to count yet, or the cost of some of its calls cannot be calculated, for example for a Subscription credential.
- **"Some data failed to load"**: credential statistics could not be read for some channels, so the totals show "—"; expand the channel and click **Retry**.
- **When data refreshes**: data is read when you open or refresh the page and is not real-time.

(Screenshot: The BYOK list shows cost, token usage and status by provider channel and credential.)

## Managing credentials

Click the edit button in the list to open the Credentials step:

| Action | How |
| --- | --- |
| Replace a key | Enter the new key in API Key. Leaving it blank keeps the current key (the field shows "Leave blank to keep the current key"). Saved keys show only a masked prefix such as `sk-demo****`, and the plaintext cannot be viewed |
| Disable / enable | Toggle Enabled. Newly added credentials are always saved as enabled; to disable one, save first, then edit again and turn it off |
| Reorder | Move rows up or down in the Order column; lower numbers are tried first |
| Add a credential | Click **Add a credential from another account** |
| Delete a credential | Click the delete button at the end of the row; at least one credential must remain. To pause the whole channel, click the disable button in the list |

All changes take effect after you click **Save configuration** and reach the gateway within seconds. After replacing a key, use **Test** or **Test connection** to confirm that the new key works. For troubleshooting, the credential name and masked prefix are enough; you never need to share the full key.

(Screenshot: Replace, disable and reorder credentials in Credentials; leave an existing key blank to keep it unchanged.)

## Health status

- A newly added credential is checked once automatically after saving, by reading the provider's model list. Status on a credential row shows Healthy, Checking, Error or Disabled.
- A provider channel row shows Error when every credential fails its check; click it to see the failing credentials, the failure reasons and the Last checked time, and to **Re-check** or **Review config**. When only some credentials fail, the row shows Near limit; expand the channel to see each credential's status.
- Status is informational and does not affect routing: a credential showing Error is still tried. Once you confirm that a key is invalid, replace or disable it promptly. After you replace a key, its status in the list does not update automatically; when the channel shows Error, click it and choose **Re-check**.

## Credential limits

Credentials with Token-based billing can have limits: click **Set limits** in the Usage and cost limits column and fill in Monthly and Total caps under Cost limits (¥) and Token limits (millions). Leave a field blank or enter 0 for no limit.

- **When a limit is reached**: the credential is skipped during routing, and the gateway goes on to the next credential in the same channel, then platform credentials and other channels. When every usable credential has reached its limit, the gateway returns 429 `all upstream credentials for this model are rate limited` (`error.code` `upstream_quota_exhausted`); see [429: rate limits and quotas](https://platform.lyrouter.com/ai_gateway/docs/rate-errors/en).
- **How usage is counted**: usage is counted after a request completes, so the request that crosses the limit still completes normally. Counting has a short delay, so leave some headroom. Monthly limits reset on the 1st of each month; Total limits never reset.
- **Unit of the token limit**: Token limits (millions) is entered in millions of tokens: `10` means 10 million tokens and `1.25` means 1.25 million. After saving, check the limit under Monthly tokens on the credential row.
- **Controlling provider spend**: to strictly control what you spend with the provider, also set a quota cap for the account in the provider's console.

## FAQ

### The cost in the list does not match the provider's bill. Which one is right?

**Answer:** The provider's bill. The list estimates cost from the list price and discount set in BYOK, and the provider's actual prices, discounts and billing rules may differ. The platform service fee is not included either; check it in Consumption under **Subscription & Credits**.

### BYOK uses my own key, so why do I get 402?

**Answer:** BYOK calls pay the platform service fee from your Credits balance. Look at `error.message`: `insufficient credit balance` means the balance is below the service fee this call needs to reserve, or the account has never been topped up (`error.code` `balance_missing`); top up to recover. `subscription expired; renew to continue` means the account's subscription has expired; renew to recover. See [Unavailable models](https://platform.lyrouter.com/ai_gateway/docs/unavailable/en).

### I set a token limit and calls soon return 429. What should I do?

**Answer:** Check whether the limit was saved by an earlier version. Earlier versions stored Token limits (millions) as a raw number of tokens, so a `10` entered then allows only 10 tokens and is reached after the first call. The editor now shows the value in millions, so such a limit appears as a tiny decimal and is not scaled up automatically. Edit the BYOK and enter the limit again in millions under Set limits, for example `10` for 10 million tokens, then save.