Errors and retries

Diagnose failures with errors and request IDs.

HTTP 429 can mean local admission pressure, a full queue or upstream throttling. Read the error and Retry-After; it does not imply unlimited RPM or TPM.

Honor Retry-After and use bounded exponential backoff with jitter. Cap attempts and total time. For video jobs that may already exist, look up the job ID before submitting again.

Retain x-mientaymedia-request-id when present and the failure time for investigation. Exclude API keys and sensitive payloads from reports.

Error code

HTTP	Error type	Reason
400	invalid_request_error	Wrong JSON or missing parameters
401	authentication_error	Missing key, wrong key or revoked key
402	insufficient_balance api_key_monthly_limit outstanding_undercharge	Read error.type: insufficient_balance means available funds are insufficient; api_key_monthly_limit means the key reached its monthly spending cap; outstanding_undercharge means an unpaid amount from a previous request needs reconciliation. For a key cap, check Dashboard → Keys; adding wallet funds does not increase that cap.
403	model_not_allowed	This API key is not allowed to use the selected model. Check its model permissions in Dashboard → Keys or select an allowed model.
413	request_too_large	The body exceeds 20 MB or the input exceeds a model/provider-specific limit. Read the message and reduce context, images or files; a body below the gateway limit can still receive 413.
429	rate_limit_error	HTTP 429 can mean local admission pressure, a full queue or upstream throttling. Read the error and Retry-After; it does not imply unlimited RPM or TPM.
502	api_error	Unable to connect model from upstream provider
503	service_unavailable	Temporarily unavailable or under maintenance; inspect the request ID and timestamp before retrying.

Balance errors may include required_vnd and available_vnd; key-cap errors may include limit_vnd and spent_vnd. Save these fields with the request ID for investigation, without sharing the API key.

{
  "type": "error",
  "error": {
    "type": "insufficient_balance",
    "message": "Số dư đã hết. Top up tại https://vietrouter.com.vn/dashboard/topup"
  }
}

Troubleshooting

View model status in Pricing

Retain x-mientaymedia-request-id when present and the failure time for investigation. Exclude API keys and sensitive payloads from reports.

Honor Retry-After and use bounded exponential backoff with jitter. Cap attempts and total time. For video jobs that may already exist, look up the job ID before submitting again.

Symptom	Common causes	How to handle
404 or “Not Found”	Wrong base URL — extra or missing /v1 suffix.	Anthropic-style tools use https://vietrouter.com.vn; OpenAI-style tools use https://vietrouter.com.vn/v1.
401 authentication_error	Wrong key, revoked key, or the app is still using a saved old key.	Create a new key in the dashboard, remove the old key from the app, then restart the app.
402 insufficient_balance	Wallet balance is empty.	Top up on the Top-up page.
429 rate_limit_error	HTTP 429 can mean local admission pressure, a full queue or upstream throttling. Read the error and Retry-After; it does not imply unlimited RPM or TPM.	Honor Retry-After and use bounded exponential backoff with jitter. Cap attempts and total time. For video jobs that may already exist, look up the job ID before submitting again.
Claude Code keeps asking you to sign in	The machine still has an old Anthropic account session.	Run /logout in Claude Code, set ANTHROPIC_AUTH_TOKEN, then reopen the terminal.
App says the model does not exist	Wrong model name, or the app adds a provider prefix on its own.	Call GET /v1/models for the exact names, and drop prefixes like anthropic/ unless the app requires them.
Image requests fail	The app sends images in a format the model rejects, or the image is too large.	Chỉ dùng model có nhãn Vision, nén ảnh và giữ toàn bộ yêu cầu dưới 20 MB.
Environment variables have no effect	An old terminal still has stale values, or the app reads config from its own file.	Open a new terminal (Windows: sign out/in), and check whether the app has a config file that overrides environment variables.

Examples receive source review and local checks; this does not establish compatibility with every app version. Check settings, send a small request and confirm usage before production use.