APIXO API 使用两类错误码：
- HTTP 状态码 — 请求失败时立即返回
- 任务失败码 — 任务处理失败时在状态查询中返回
┌─────────────────────────────────────────────────────────────┐
│ API Request Flow │
├─────────────────────────────────────────────────────────────┤
│ │
│ POST /generateTask/{model} │
│ │ │
│ ├── Fail ──→ HTTP Status Code (400/401/429...) │
│ │ Request rejected immediately │
│ │ │
│ └── Success ──→ 200 + taskId │
│ Request accepted, task processing │
│ │ │
│ ▼ │
│ GET /statusTask/{model}?taskId=xxx │
│ │ │
│ ├── state: success ──→ resultUrls │
│ │ │
│ └── state: failed ──→ Task Failure Code │
│ (failCode/failMsg) │
│ │
└─────────────────────────────────────────────────────────────┘
| Type | When Triggered | Meaning | Example |
|---|
| HTTP Status Code | 请求立即返回时 | 请求本身有问题 | 401 Invalid API Key |
| Task Failure Code | 查询任务状态时 | 请求已接受但处理失败 | SensitiveContentDetected |
HTTP 状态码
| Code | Name | Description | Action |
|---|
200 | OK | 请求成功 | 正常处理响应 |
400 | Bad Request | 请求参数无效 | 检查请求体 |
401 | Unauthorized | API 密钥无效或缺失 | 检查 API 密钥 |
402 | Payment Required | 余额不足 | 充值账户 |
403 | Forbidden | 内容违反政策 | 修改内容 |
404 | Not Found | 资源不存在 | 检查模型 ID 或任务 ID |
429 | Too Many Requests | 超过速率限制 | 稍后重试 |
500 | Server Error | 服务器内部错误 | 稍后重试 |
503 | Service Unavailable | 服务暂时不可用 | 稍后重试 |
任务失败码
任务失败时，响应中包含 failCode 和 failMsg：
{
"code": 200,
"message": "success",
"data": {
"state": "failed",
"failCode": "SensitiveContentDetected",
"failMsg": "Your content was flagged by OpenAI as violating content policies."
}
}
内容政策违规
| failCode | Description | Solution |
|---|
SensitiveContent | 内容违反政策 | 修改 prompt，避免敏感内容 |
SensitiveContentDetected | 内容被判定为违规 | 调整 prompt 内容 |
InputImageSensitiveContentDetected | 输入图片含违规内容 | 使用合规图片 |
InputOutputSensitiveContentDetected | 输入或输出含敏感内容 | 更换输入后重试 |
NSFW | 检测到 NSFW 内容 | 使用合规内容的输入 |
ProhibitedContentDetected | 检测到禁止内容 | 更换其他输入 |
Prompt 错误
| failCode | Description | Solution |
|---|
PromptLengthExceeded | 超过 prompt 长度限制 | 缩短 prompt |
PromptInvalid | prompt 无效或被拒绝 | 检查 prompt 格式和内容 |
图片/媒体错误
| failCode | Description | Solution |
|---|
ImageFormatIncorrect | 图片格式不正确 | 使用 JPEG、PNG 或 WebP |
InvalidImageSize | 图片尺寸无效 | 检查尺寸要求 |
Upload error | 图片超过 10MB | 压缩至 10MB 以下 |
INVALID_IMAGE_URL | 无法访问图片 URL | 检查 URL 可访问性 |
INVALID_LORA_URL | 无法下载 LoRA 模型 | 检查 LoRA URL |
速率限制与配额
| failCode | Description | Solution |
|---|
RateLimited | 被限流，请稍后重试 | 降低请求频率，等待后重试 |
RateLimitExceeded | 超过速率限制 | 稍后重试 |
InsufficientQuota | 配额不足 | 检查账户余额 |
处理与系统错误
| failCode | Description | Solution |
|---|
Timeout | 响应超时 | 稍后重试 |
Task TimeOut | 任务超时，生成失败 | 换其他任务 |
BadRequest | 缺少必填参数 | 检查请求参数 |
MissingParameter | 缺少必填参数 | 参考 API 文档，补充参数 |
错误响应示例
HTTP 错误（立即返回）
400 - 参数错误
{
"code": 400,
"message": "Prompt exceeds provider limit (max 2000 chars)",
"data": null
}
{
"code": 401,
"message": "Invalid or missing API key",
"data": null
}
{
"code": 429,
"message": "Provider rate limited, please retry later",
"data": null
}
{
"code": 504,
"message": "Provider timeout, please retry later",
"data": null
}
任务失败（查询状态时）
内容违规
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "SensitiveContentDetected",
"failMsg": "Your content was flagged by OpenAI as violating content policies.",
"createTime": 1767965610929,
"completeTime": 1767965652317
}
}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "NSFW",
"failMsg": "NSFW, Try different input please.",
"createTime": 1767965610929,
"completeTime": 1767965652317
}
}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "ImageFormatIncorrect",
"failMsg": "Image format is incorrect",
"createTime": 1767965610929,
"completeTime": 1767965652317
}
}
错误处理最佳实践
只有 429、500 和 504 适合自动重试。其他错误需先修正请求。
1. 重试策略
| Error Type | Retry? | Strategy |
|---|
400（参数错误） | No | 修正参数后重试 |
401（认证失败） | No | 检查 API 密钥 |
429（限流） | Yes | 指数退避，等待 60 秒后重试 |
500（服务器错误） | Yes | 指数退避，最多 3 次 |
504（超时） | Yes | 等待后重试，最多 3 次 |
| 内容违规 | No | 修改内容后重试 |
| 图片错误 | No | 修正图片后重试 |
2. 指数退避示例
async function retryWithBackoff(fn, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error) {
if (error.code === 429 || error.code >= 500) {
const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
await new Promise(resolve => setTimeout(resolve, delay));
} else {
throw error;
}
}
}
throw new Error('Max retries exceeded');
}
3. 内容审核建议
内容审核由上游 AI 提供商执行。违规无法通过 APIXO 申诉——请修改内容后重新提交。
- 避免暴力、色情、政治敏感内容
- 确认输入图片符合内容政策
- 使用明确、具体的描述，避免歧义
- 先用简单、安全的内容测试
4. 监控与日志
建议记录以下信息以便调试：
taskId — 任务唯一标识failCode — 失败码failMsg — 失败信息- 请求参数（脱敏后）
提供商特定错误
OpenAI
| failCode | Description |
|---|
SensitiveContentDetected | 内容被 OpenAI 判定为违规 |
InputImageSensitiveContentDetected | 包含真人照片的图片不受支持 |
MidJourney
| failCode | Description |
|---|
Website TimeOut | MidJourney 网站多次请求无响应 |
INVALID_TASK_ID | 用于 upscale/vary 的前一任务 ID 无效 |
Seedream（ByteDance）
| failCode | Description |
|---|
outputimagesensitivecontentdetected | 输出图片含敏感内容 |
InvalidImageSize | 图片尺寸无效 |
FAQ
Q: 收到 429 后应等待多久？
A: 建议等待 60 秒后重试，或采用指数退避策略。
Q: 如何避免 PromptLengthExceeded？
A: 各模型 prompt 长度限制不同，请查阅模型文档。通常建议控制在 2000 字符以内。
Q: 能否申诉 SensitiveContentDetected？
A: 这是上游 AI 提供商的内容审核结果。建议修改内容后重新提交。
Q: 出现 5xx 错误应如何处理？
A: 多为临时服务器问题。可用指数退避重试，最多 3 次。若持续出现，请联系客服。
为什么任务状态返回 200 但 state 是 failed？ HTTP 200 表示接口请求本身成功，但生成任务失败。具体错误见 failCode 和 failMsg，而非 HTTP 状态码。
200 但 state 是 failed？
A: HTTP 200 表示接口请求成功，但任务执行失败（如内容违规）。错误信息在 failCode 和 failMsg 中。
技术支持
若持续遇到错误，联系客服时请提供：
taskId — 失败任务 IDfailCode — 错误码- 请求参数（脱敏后）
- 错误发生时间
技术支持：support@apixo.ai