OneMux/Docs/Frequently Asked Questions

Frequently Asked Questions

Encountering errors when calling the API? Quickly identify issues by HTTP status code. This page lists the most common error codes and solutions. Most issues can be resolved independently within 1 minute.

Quick Troubleshooting

When your code returns an error, first find the HTTP status code (such as 401 or 429), then follow the corresponding steps:

Status CodeCauseSolution
401Invalid API KeyCheck the key format (sk-xxx) and validity
402Insufficient balanceAdd funds in the console
404Incorrect model IDCopy the correct ID from the model page
429Requests sent too quicklyReduce the request frequency and try again after 10 seconds
500Upstream service failureTry again later or switch models

401 - Invalid API Key

Most common causes:

  • Extra spaces were included when copying
  • Incorrect format (does not start with sk-)
  • The key has been deleted

Quick fix:

# ✅ Correct format
api_key = "sk-1234567890abcdef"

# ❌ Common errors
api_key = " sk-1234567890abcdef "  # Spaces before and after
api_key = "1234567890abcdef"       # Missing sk- prefix

Go to the console to copy the key again or create a new one.

402 - Insufficient Balance

Your account balance is insufficient to pay for this request.

Go to the billing center to add funds.

Note: Long-context requests (such as Gemini processing 1 million tokens) reserve the maximum possible cost in advance, so make sure your balance is sufficient.

404 - Model Not Found

Common causes:

  • Typo in the model ID
  • An old model name is being used (for example, gpt-4o has been replaced by gpt-6.1-sol)
  • Incorrect Base URL path

Solution:

Get the Correct Model ID

  1. 1

    Visit the Model Page

    Open https://onemux.net/models

  2. 2

    Find the Required Model

    Search or browse to find the target model

  3. 3

    Copy the Model ID

    Click the copy button or manually copy the complete ID

Confirm that the Base URL is https://api.onemux.net/v1 (note the trailing /v1)

429 - Requests Sent Too Quickly

Too many requests were sent in a short period, triggering the rate limit.

Solution:

  • Reduce the request frequency
  • Wait 10-30 seconds and try again
  • Add automatic retry logic (see the error handling documentation)
  • Reduce the number of concurrent tasks

500/502/503 - Service Failure

The upstream model service is temporarily unavailable.

Solution:

  • Wait 10-30 seconds and try again
  • Switch to another model
  • Check the status page for the service status

Troubleshooting Order for Uncertain Issues

Troubleshoot Step by Step

  1. 1

    Check Your Balance

    Log in to the console and confirm that your balance is sufficient

  2. 2

    Check the API Key

    Copy the complete key again and make sure there are no spaces

  3. 3

    Check the Model ID

    Copy it again from the model page

  4. 4

    Check the Base URL

    Confirm that it is https://api.onemux.net/v1

  5. 5

    Restart the Software

    Save the configuration and restart the client