Frequently Asked Questions
BYOK Related Questions
What is BYOK (Bring Your Own Key)?
BYOK means "Bring Your Own Key". In XAI Router, this means you use your own API Keys obtained from official platforms like OpenAI, Claude, DeepSeek, rather than purchasing keys from XAI. These keys are stored in protected form by the platform for unified routing and governance, and are only used by the system within authorized request flows on your behalf.Core Advantages:
- ✅ Full Control: Key ownership belongs to you; replace, delete, or migrate anytime
- ✅ Zero Markup: API call charges deducted directly from your official account with no markup
- ✅ Cost Transparency: View original billing directly on official platforms (e.g., OpenAI Dashboard)
- ✅ Data Sovereignty: Sensitive credentials are kept in protected custody, and system admins cannot directly view their original contents
What's the difference between XAI Router BYOK and OpenRouter?
| Feature | XAI Router | OpenRouter |
|---|---|---|
| Must Use BYOK | ✅ BYOK Architecture, no other option | ❌ Optional BYOK or platform paid pool |
| BYOK Fee | ✅ Completely free | ❌ 5% service charge |
| Free Tier | ✅ Unlimited (use your own keys) | ⚠️ 1M requests/month then paid |
| Self-Hosted | ✅ Supported | ❌ Cloud-only |
Are my Provider Keys safe? Will XAI misuse them?
Absolutely not. XAI Router uses protected custody and authorized runtime controls:Technical Safeguards:
- 🔒 Protected Custody: The platform stores protected sensitive credential material rather than exposing ordinary plaintext secrets
- 🔒 Isolated Protection: Sensitive credentials from different accounts are isolated in both custody and usage boundaries
- 🔒 No Super-Admin: System admins and database admins cannot decrypt your keys
- 🔒 Audit Logs: All key usage is fully logged and traceable to specific requests
- 🔒 Even if Database Leaks: Attackers cannot recover your Provider Keys
- SOC 2 Type II certification (planned)
If I want to stop using XAI Router, how do I migrate my data?
The biggest advantage of BYOK is zero vendor lock-in:Migration Steps:
- Collect integration settings: gather the configuration you currently use through the console or your existing integration records
- Copy Keys: Your original Provider Keys are always on official platforms (e.g., OpenAI Dashboard), just copy directly
- Switch base_url: Change Base URL in your application or new platform
- Complete Migration: No approval needed, takes effect immediately
- ❌ Cannot export keys (you never owned them)
- ❌ Need to reapply for all official API Keys
- ❌ Historical usage data cannot be migrated
In BYOK mode, why does XAI Router still need my XAI API Key?
This is a two-credential model:- Provider Key (Upstream Key): The original key obtained from official platforms like OpenAI or Claude, added to XAI Router and kept in protected custody; it is only used by the system within authorized request flows on your behalf
- XAI API Key (Virtual Key): The proxy key assigned by XAI Router (format:
sk-Xvs...), used for:- Authenticating your identity
- Routing requests to the correct Provider Key pool
- Carrying your access-control and governance rules
- Recording usage and audit information
Your App → Call with XAI API Key → XAI Router verifies and routes → Calls official API with your Provider Key → Charges deducted from your official account
Technical Issues
Why do some API calls return a 404 Not Found error?
This is usually because your `base_url` is configured incorrectly. Many libraries (like LangChain) require the `base_url` to include the `/v1` suffix, not just the domain name.Please check your configuration and ensure it is set to `https://api.xairouter.com/v1` (for OpenAI-compatible interfaces).
Why am I getting a "401: Incorrect API key provided..." error?
This error indicates that your request was sent to OpenAI's official servers instead of the XAI Router proxy service. This typically happens when you have only configured the API Key but have not changed the API request address (`base_url`) to `https://api.xairouter.com`.What should I do if the open-source project I'm using doesn't support configuring a `base_url`?
In this situation, you will need to find the project's source code and hardcode the API request address from `api.openai.com` to `api.xairouter.com`.Why do I get a 401 Unauthorized error when calling user management APIs (e.g., /x-users)?
To prevent abuse, calling core management APIs (such as creating/managing child users) has a minimum balance requirement for the calling account. Typically, your account balance needs to be greater than `\$100` to gain the necessary permissions. Please ensure your account has sufficient funds.What are the requirements for creating a child user?
Creating a child user requires meeting two main conditions: 1. Your parent account balance must be greater than `\$100`. 2. The initial top-up amount for the newly created child user cannot be less than `\$2`.In the XAI XAPI system, every account is independent. As long as a child user's balance also meets the above conditions, it can also create its own child users.
Why does my account report "Insufficient balance" even though I still have credit?
To prevent overdrafts and asset loss, the system prohibits new API calls when the account balance falls below `\$1`. Please top up your account in a timely manner.Why am I seeing 429 Too many requests / Rate limit XXX reached?
This means the current account or model has hit a limit window. Common reasons are `RPM`, `RPH`, `RPD`, `TPM`, `TPH`, and `TPD`. If the error explicitly says `RPH`, the model has exhausted its requests-per-hour limit.Request-count limits are checked before forwarding. `TPD` is accrued from successful token usage after the request completes, so if one successful request pushes the day over the cap, `429 TPD` usually starts on the next request.
Recommended actions:
- Reduce concurrency and add exponential backoff
- Check the exact reason first: `RPM/RPH/RPD/TPM/TPH/TPD`
- Spread traffic across time windows or models
- Contact your admin to increase the relevant quota or model `ModelLimits`
RPH is 300 - why did only 40 requests succeed?
RPH counts requests that enter the window check, while usage stats only record successful requests. Concurrency, retries, or failures before the threshold is hit can consume RPH without appearing in successful usage.Example: 300+ attempts in an hour, 40 succeeded, and the rest failed or were rate-limited, so you see "40 successes" while the RPH limit is exhausted. Once active `cooldown` is in effect, further blocked retries no longer push the counter upward without bound.
Are concurrent requests all blocked? How long do I need to wait?
They are evaluated one by one: requests before the limit is hit can succeed, and requests after the limit will return 429.Recovery time depends on which limit was hit:
- `RPM/TPM`: typically about 1 minute
- `RPH/TPH`: typically about 1 hour
- `RPD/TPD`: natural-day quota, recovered when the server-side day ends
Why does it feel like my limit never resets?
Check the reason in the 429 response first:- `RPM/RPH/TPM/TPH`: you are usually still inside a short window or its `cooldown`
- `RPD/TPD`: you have exhausted the quota for the current server-side business day and need to wait for the next day boundary