Troubleshooting

Common errors, causes, and fixes during integration and API calls.

Authentication errors

Error message	HTTP status	Cause	Solution
`invalid api key`	401	API key is invalid, expired, revoked, or disabled	Open Console → Token Management and confirm the token is active; recreate and copy the full sk-… key if expired
`invalid_api_key`	401	Missing Authorization header or incorrect Bearer token format	Use Authorization: Bearer `API_KEY` with a single space after Bearer
`forbidden`	403	Token is not allowed to access this model or endpoint	Check model permissions and group on the token; confirm the model is enabled for that token

Routing and model errors

Error message	HTTP status	Cause	Solution
`no model config found for: {model}`	404	Requested model ID does not exist or is not configured on the gateway	Verify the model name in the model list; call GET /v1/models for available models
`model field is required`	400	Request body is missing the model field	Add "model": "gpt-4o" (or another valid model ID) to the JSON body
`invalid or empty requested model`	400	model is empty or malformed	Use a non-empty string that exactly matches the console model ID (case-sensitive)
`unknown api path`	404	Wrong API path or Base URL	OpenAI-compatible Base URL should be ; chat path is /chat/completions

Request parameter errors

Error message	HTTP status	Cause	Solution
`invalid_request_error`	400	Invalid JSON or wrong field types	Set Content-Type: application/json; compare fields with the API reference
`messages field is required`	400	Chat Completions request is missing the messages array	Add messages: [{"role": "user", "content": "..."}]
`max_tokens not supported`	400	Some newer models do not support max_tokens	Use max_completion_tokens instead, or check the model docs for supported fields
`prompt is required`	400	Video/image request is missing prompt or other required fields	Fill model, prompt, and other required fields per the video/image API reference

Quota and rate-limit errors

Error message	HTTP status	Cause	Solution
`rate_limit_exceeded`	429	Request rate exceeds token or account limits	Lower concurrency and QPS; use exponential backoff; adjust token rate limits in the console if needed
`quota exceeded`	429	Daily or monthly token quota is exhausted	Check remaining quota on the token; ask an admin to raise limits or wait for reset
`too many requests`	429	Upstream channel or gateway is temporarily overloaded	Retry after a few seconds; avoid burst traffic; use async queues where possible

Billing and balance errors

Error message	HTTP status	Cause	Solution
`insufficient balance`	402	Account balance is too low to charge the request	Top up in Console → Wallet; pay-as-you-go models need enough balance for the estimated cost
`insufficient_quota`	402	Wallet quota is insufficient	Review usage records and wallet balance; per-call models need remaining call credits
`billing hard limit reached`	403	Account or token hit a spending hard cap	Raise the spending cap in the console or ask an admin to increase limits

Server errors

Error message	HTTP status	Cause	Solution
`server_error`	500	Internal gateway or upstream failure	Retry later; if it persists, note request time and model, then contact us
`upstream error`	502	Upstream model service is down or timed out	Switch model or channel; for async jobs, poll task status later
`service unavailable`	503	Maintenance or channel temporarily offline	Check site announcements; retry later or use another model
`timeout`	504	Request timed out (common for long video/large image jobs)	Use async video APIs and poll status; reduce prompt complexity or resolution

Common scenarios

Base URL mistakes

❌ https://token.easyapi.com/chat/completions
✅ /chat/completions          # OpenAI-compatible chat
✅ /v1/messages               # Claude native (Anthropic-compatible)

max_tokens not supported

❌ {"model": "gpt-4o", "max_tokens": 100}
✅ {"model": "gpt-4o", "max_completion_tokens": 100}  # required on some newer models

API key format

❌ Authorization: sk-xxxxxxxx
✅ Authorization: Bearer sk-xxxxxxxxxxxxxxxx   # Bearer prefix and space required

Use async flow for video

❌ Waiting on POST /v1/chat/completions for video (likely timeout)
✅ POST /videos → poll GET /v1/videos/ → download content or video_url

Still stuck?

Submit a ticket via Contact us with request time, model ID, and the error response (never share your full API key). See also Error codes and Usage records for billing and rate-limit issues.