Errors and Troubleshooting

Authentication, balance, model permission, parameter, timeout, and rate-limit troubleshooting

This page only summarizes issues already mentioned in the API documentation and tutorials. When no exact error code is documented, the issue is described as possible 400, 401, 403, 404, timeout, or request failure.

Common Issues

Category	Possible Symptom	What to Check
Authentication failure	`401`	Check whether the API Key is missing, whether the full `sk-` prefix is preserved, and whether you use `Authorization: Bearer sk-...`.
Token unavailable	`401` / `403`	Check whether the token is disabled, expired, out of quota, or blocked by IP restrictions.
Insufficient balance	`403` or request failure	Check wallet balance, top-up records, and consumption changes.
Model missing or not allowed	`403` / `404`	Use List Available Models to confirm whether the current token can see the target model.
Incorrect endpoint	`404`	Check whether the Base URL matches the tool. Codex/OpenAI-compatible tools usually use `https://api.routescope.ai/v1`; Claude Code usually uses `https://api.routescope.ai`.
Parameter error	`400`	Check whether protocols are mixed. OpenAI Chat uses `messages`, Gemini uses `contents[].parts[]`, and Claude Messages requires `max_tokens`.
Claude Code experimental betas	`400`	May appear as `context_management: Extra inputs are not permitted`. Disable experimental betas as described in the tool guide.
Timeout	Timeout	High-resolution images, long video tasks, long text, or slow upstream responses may time out. Query async task status when applicable.
Rate limit	`429` or request failure	RPM, TPM, and concurrency limits follow backend configuration and API responses.

Authentication Failure

Check these first:

The request header should be Authorization: Bearer sk-your-token.
The copied secret should be complete and should keep the sk- prefix.
The token should not be disabled, expired, or blocked by IP restrictions.
The client field should match the tool, such as OPENAI_API_KEY in Codex auth.json and ANTHROPIC_AUTH_TOKEN for Claude Code.

Insufficient Balance

If the key and model are correct but calls still fail, check:

Whether current balance is sufficient.
Whether recent top-up has completed.
Whether usage-log consumption matches expectations.

Model Missing or Not Allowed

Common causes:

The model ID was typed incorrectly.
The current token restricts available models.
The account or group has not enabled the model.
The client model is not returned by /v1/models or /v1beta/models.

OpenAI-compatible model list:

curl https://api.routescope.ai/v1/models \
  -H "Authorization: Bearer sk-your-token"

Gemini-native model list:

curl https://api.routescope.ai/v1beta/models \
  -H "Authorization: Bearer sk-your-token"

Parameter Errors

Do not mix protocol fields:

Protocol	Correct Structure
OpenAI Chat Completions	`POST /v1/chat/completions`, body includes `model` and `messages`.
Claude Messages	`POST /v1/messages`, body includes `model`, `messages`, and `max_tokens`.
Gemini Generate Content	`POST /v1beta/models/{model}:generateContent`, body uses `contents[].parts[]`.
Imagen Predict	`POST /v1beta/models/{model}:predict`, body uses `instances` and `parameters`.
OpenAI-style image editing	`POST /v1/images/edits`, OpenAI-style editing requires `multipart/form-data` source image upload.
Doubao Seedream editing	`POST /v1/images/edits`, reference images are passed through the JSON `image` field.

Request Timeout

These cases may time out:

High-resolution image generation or many images in one request.
Long video generation tasks.
Slow upstream channels.
Oversized request bodies or too many reference images.

For video and async image tasks, save the task ID and query status through task query endpoints or task logs.

Rate Limits

Exact RPM, TPM, and concurrency values follow backend configuration and API responses. The current documentation does not list one fixed rate-limit code, so do not hardcode a single error code in business logic.