Troubleshooting

First determine whether failure occurs in client configuration, QuotaAPI authentication and scheduling, the target model, or a payment provider. Unlimited retries can amplify rate limits, duplicate work, or duplicate payments.

Minimum diagnostic context

Record:

1. Time and timezone.
2. HTTP method and path.
3. Model, group name, and API Key name.
4. HTTP status, response error, and request_id.
5. Streaming or media mode, client name, and version.
6. A minimal reproducible request.

Never log or send a full Authorization header, API Key, Cookie, payment secret, or object-storage credential.

Status code reference

Status	Common meaning	First check
400	Invalid body, parameter, model, or protocol	Endpoint docs and a minimal curl
401	Missing, invalid, or malformed API Key	Bearer header, Key status, client variables
402	Insufficient USD balance or subscription quota	Balance, quota windows, recent charges
403	Group, model, image capability, or IP rule denied	Bound group, feature flags, IP rules
404	Platform does not support the endpoint, or resource belongs to another Key	Compatibility matrix, resource ID
429	User, Key, account, or target-platform limit	Retry-After, concurrency, quota windows
500 / 502	Gateway or target-platform failure	request_id, limited retry later
503	No schedulable account or dependency unavailable	Account pool, model mapping, cooldown state

Isolating the client with curl

curl -i https://quotarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_QUOTAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "messages": [{"role":"user","content":"Reply with OK"}],
    "max_tokens": 16
  }'

If curl succeeds while an SDK fails, inspect Base URL, environment variables, proxy, timeout, and selected protocol. If curl also fails, keep the full status and sanitized body.

Client configuration

• Claude Code uses the Anthropic Messages Base URL.
• Codex CLI requires config.toml, auth.json, and wire_api = "responses".
• Gemini CLI uses GOOGLE_GEMINI_BASE_URL, GEMINI_API_KEY, and GEMINI_MODEL.
• OpenAI SDKs normally use https://quotarouter.ai/v1 as Base URL.

Do not accidentally produce /v1/v1, and do not use a console login token as an API Key.

Account test passes while user API returns 503

An administrator account test connects directly to one account. It proves credentials and target access only. User API scheduling also filters by Key-bound group, platform, model mapping, schedulable state, concurrency, quota, and cooldown. Check:

1. group_id, provider, model, and account_select_failed in logs.
2. Whether the account belongs to the group and matches its platform.
3. Whether the requested model maps to a model supported by the account.
4. Whether 429, 402, authentication failure, or concurrency temporarily cooled the account.

429 while the account appears usable

A 429 can apply only to one model, region, project, window, or concurrency level. It does not necessarily mean permanent account failure. Honor Retry-After and cap retries. With multiple accounts, QuotaAPI can fail over according to policy; when every candidate is cooled down or incompatible, the final user response may become 503.

Empty stream or response appears only after refresh

Wait for the chat page's reconciling state. The server may have persisted a response while the SSE connection failed to deliver its tail to the browser. Record conversation ID, request_id, and browser network error. API clients must distinguish normal [DONE], error events, and premature connection termination.

Images and videos

• Console image chat waits up to 120 seconds; do not resubmit while processing.
• Prefer async image tasks for long API work and keep polling the original task_id.
• A 404 often means the group platform does not support media or the feature is disabled.
• Video requires a Grok target, and lookup must use the original user and API Key.
• For upload failures, check format, size, and object-storage configuration.

Payments and recharge

• amount is too small: below provider or currency minimum.
• Payment method unavailable: disabled instance, unsupported currency, amount limit, region/device ineligibility, or exhausted daily capacity.
• Charged without credit: do not pay again; refresh order status and keep the order number.
• HKD charged versus USD credited is expected FX behavior; inspect order fx_rate and payment currency.
• Cryptocurrency requires the exact network, address, and amount.

Opening a ticket

If these steps do not resolve the issue, use Tickets and Support with time, endpoint, model, group, status, request_id, and minimal reproduction. Add an order number for payment issues or batch ID for batch images. Never include secret credentials.