HAI Gateway Docs

FAQ

Answers to frequently asked questions

General

What's the difference between an Access Token and an official API Key?

An Access Token is a unified key issued by our platform. It can call all supported provider APIs with unified billing — no need to apply for separate API keys from each provider.

Why do you recommend Claude Code / Codex?

These are official terminal-based coding tools that run directly in your project directory. They understand your entire codebase context and can perform code modifications, bug fixes, and more — far more efficient than web-based chat.

Environment variables not taking effect?

Make sure you:

  1. Reopen your terminal after setting the variable
  2. Check for typos in the variable name (case-sensitive)
  3. On Windows, use "User variables" instead of "System variables"

Authentication

"API key is Missing" (401)

Cause: The request is missing an authentication header.

Solution: Add the appropriate auth header for your provider:

  • OpenAI: Authorization: Bearer sk-pat-xxx
  • Anthropic: x-api-key: sk-pat-xxx
  • Google: x-goog-api-key: sk-pat-xxx or query param ?key=sk-pat-xxx
"Incorrect API key format is provided" (401)

Cause: The header format is incorrect when using an OpenAI endpoint.

Solution: OpenAI endpoints require the Bearer format:

✗ Authorization: sk-pat-xxx

✓ Authorization: Bearer sk-pat-xxx

"Incorrect API key is provided" (401)

Cause: The Access Token is invalid or has been deleted.

Solution:

  • Verify the token starts with sk-pat-
  • Confirm the token is still valid (it may have been reset or deleted)
  • Go to the "Personal Tokens" page on the platform to create a new token
Anthropic endpoint doesn't work with Authorization: Bearer?

Cause: Anthropic endpoints use a different auth header than OpenAI.

Solution: Anthropic endpoints require x-api-key, not Authorization: Bearer. You also need to include the anthropic-version: 2023-06-01 header.

Quota & Rate Limiting

"You have reached your usage limits." (402)

Cause: Account balance and credit limit have been exhausted.

Solution:

  • Check your current balance and spending on the platform
  • Contact an administrator to top up or adjust your credit limit
  • Check for abnormally high usage (view details in usage analytics)
"Too many requests!" (429)

Cause: Requests per minute (RPM) exceeded the limit.

The system uses a token bucket algorithm to control request frequency at both the tenant level and individual Access Token level.

Solution:

  • Reduce request frequency and add appropriate delay/backoff strategies
  • If rate-limited at the token level, create multiple tokens to distribute requests
  • Contact an administrator to increase your RPM limit

Model Issues

"Model xxx is not accessible: Not Found!" (403)

Cause: The requested model ID does not exist in the system.

Solution:

  • Check the model ID for typos (watch for case sensitivity, date suffixes, etc.)
  • Call the List Models endpoint to see currently available models
  • Confirm the model has been configured on the platform
"Model xxx is not accessible: Not Allowed!" (403)

Cause: Your tenant is not on the model's access whitelist, or has been blacklisted.

Solution: Contact the platform administrator to verify your tenant's access permissions for the model.

Still have questions?

If you encounter an issue not listed above, please contact the platform administrator for assistance.