Skip to content
中

Account API errors and rate limits

Handle Account API authentication errors, missing scopes, rate limits, and temporary failures.

Updated Reviewed
View Markdown

Use the HTTP status code to determine success. Successful responses always return 200. Errors use the following format, sometimes with additional fields to guide recovery:

{
  "error": "invalid_request",
  "field": "startTime"
}
HTTP error Action
400 invalid_request Correct the parameter named by field; do not retry unchanged
401 unauthorized Check the key, then check for revocation or expiry in the console; contact support if the account is disabled
403 insufficient_scope Add the required scope to this key in the console; replacement is unnecessary
404 not_found Check the base URL, version, and path
429 rate_limited Wait for retryAfterSeconds before retrying
500 internal Retry with a delay and an attempt limit; contact support if it persists
502 upstream_unavailable Balance or request data is temporarily unavailable; retry with backoff
Other 5xx See the response Retry with backoff and an attempt limit; provide the request time if the error persists

A 401 response does not distinguish a missing, malformed, unknown, revoked, or expired key from a disabled account. Check the key’s status and last use in the console rather than inferring the reason from the body.

Rate limits

Each key allows up to 60 calls per minute, counted in minute windows. All endpoints share the same limit. Using the same key on multiple machines also shares this limit.

When the limit is reached, the API returns 429, a Retry-After header, and JSON:

{
  "error": "rate_limited",
  "retryAfterSeconds": 23
}

Use limit=100 for batch reads and leave capacity for other jobs using the key. Contact support if you need a higher limit. Do not issue multiple keys to work around it.

Versioning and support

The current version is /open/v1/*. Within this version, existing fields will not be removed, renamed, or change type, and error codes will keep their meanings. New endpoints, response fields, and scopes may be added. Ignore unknown fields when parsing JSON. Breaking changes use a new version path, and any retirement of the old version will be announced separately.

Issue keys, change scopes, and revoke keys yourself in the console; see Get a key. For higher call limits or other questions, use online support or email contact@xiu.ai. Include the request time, HTTP status, error code, and the key’s last four characters. For a specific model request, also include its requestId. Do not send the complete key.

Navigation

Enter keywords to search

↑↓ Move↵ OpenEsc Close