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.