Documentation Index
Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
Use this file to discover all available pages before exploring further.
XHuoAPI’s response shape differs by call type:
- Synchronous HTTP responses — direct return of
POST /xxx
- Webhook callback bodies — POSTed to your
callback_url once an async task finishes
The success/failure conventions of the two are not identical.
Synchronous response: success
On success the response carries upstream business fields and usually includes a success: true marker. See each API’s API reference for exact fields.
Example (Midjourney /midjourney/imagine):
{
"success": true,
"task_id": "27a1128f-14b5-440e-a82d-510c81e6fcd4",
"image_id": "1211290228438868029",
"image_url": "https://midjourney.cdn.xhuoapi.ai/.../image.png",
"image_width": 1024,
"image_height": 1024,
"actions": ["upscale1", "upscale2", "variation1", "variation2", ...]
}
Synchronous response: error
Error responses have no success field — only error and trace_id:
{
"error": {
"code": "invalid_token",
"message": "The specified token is invalid or wrong."
},
"trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
| Field | Type | Notes |
|---|
error.code | string | Machine-readable code, see table below |
error.message | string | Human-readable description |
trace_id | string (UUID) | Request trace ID. Always include this when filing a support ticket. |
Webhook callback body
If you passed callback_url when creating the task, we POST a JSON to that URL when the task finishes. The callback envelope differs from the sync envelope — it always includes a success field:
Success callback:
{
"success": true,
"task_id": "...",
"trace_id": "...",
"image_url": "...",
"...": "...(other business fields)"
}
{
"success": false,
"task_id": "...",
"trace_id": "...",
"error": {
"code": "...",
"message": "..."
}
}
callback_url is hard to guess, or verify the incoming task_id against tasks you previously created.
HTTP status codes
| Status | Meaning | Client guidance |
|---|
200 | Success (sync result or async accepted) | Parse JSON |
400 | Malformed request | Read error.message, do not retry |
401 | Token invalid / expired / mismatched | Check credentials, do not retry |
403 | Balance exhausted / credential disabled / content moderation | Inspect error.code, usually do not retry |
404 | Endpoint not found | Verify URL |
429 | Rate limited | Retry with exponential backoff |
500 | Gateway or upstream internal error | Retry once with backoff; if still failing, escalate with trace_id |
504 | Upstream timeout | Backoff retry, or switch to async + webhook |
Verified error codes
These all come from PlatformGateway exception classes. Service-specific upstream codes (e.g. Midjourney’s own task_failed) follow each API’s own docs.
error.code | HTTP | Meaning |
|---|
bad_request | 400 | Malformed JSON payload |
no_token | 400 | Missing Authorization header |
invalid_token | 401 | Token is wrong or revoked |
token_expired | 401 | Token expired |
token_mismatched | 401 | Token does not belong to the requested service |
disabled | 403 | Credential or application disabled |
used_up | 403 | Instance balance and / or general balance exhausted |
forbidden | 403 | Content moderation rejected |
no_api | 404 | Path not registered |
too_many_requests | 429 | Rate limit exceeded |
api_error | 500 | Gateway / upstream internal error |
timeout | 504 | Upstream inference timeout |
Retry guidance
- 4xx generally should not be auto-retried (429 excepted); inspect
error.message and fix the request
- 429 / 5xx may be retried with exponential backoff and jitter
- Persist
trace_id to your logs for the fastest support resolution
Filing a ticket
Always include:
trace_id- Request URL, headers (mask the Token), and body
- Response status and body
Channels: platform.xhuoapi.ai ticket / [email protected] / status page.
