Error Codes

Complete API error code reference and troubleshooting guide

Overview

APIXO API uses two types of error codes:

HTTP Status Codes — Returned immediately when request fails
Task Failure Codes — Returned in status query when task processing fails

┌─────────────────────────────────────────────────────────────┐
│                      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	Immediately on request	Request itself has issues	`401` Invalid API Key
Task Failure Code	When querying task status	Task accepted but processing failed	`SensitiveContentDetected`

HTTP Status Codes

Code	Name	Description	Action
`200`	OK	Request successful	Process response normally
`400`	Bad Request	Invalid request parameters	Check request body
`401`	Unauthorized	Invalid or missing API Key	Check API Key
`402`	Payment Required	Insufficient balance	Top up account
`403`	Forbidden	Content violates policy	Modify content
`404`	Not Found	Resource not found	Check model ID or task ID
`429`	Too Many Requests	Rate limit exceeded	Wait and retry
`500`	Server Error	Internal server error	Retry later
`503`	Service Unavailable	Service temporarily unavailable	Retry later

Task Failure Codes

When a task fails, the response includes failCode and failMsg:

{
  "code": 200,
  "message": "success",
  "data": {
    "state": "failed",
    "failCode": "SensitiveContentDetected",
    "failMsg": "Your content was flagged by OpenAI as violating content policies."
  }
}

Content Policy Violations

failCode	Description	Solution
`SensitiveContent`	Content violates policy	Modify prompt, avoid sensitive content
`SensitiveContentDetected`	Content flagged as violation	Adjust prompt content
`InputImageSensitiveContentDetected`	Input image contains violation	Use compliant image
`InputOutputSensitiveContentDetected`	Input or output contains sensitive content	Retry with different input
`NSFW`	NSFW content detected	Use content policy compliant input
`ProhibitedContentDetected`	Prohibited content detected	Try different input

Prompt Errors

failCode	Description	Solution
`PromptLengthExceeded`	Prompt exceeds limit	Shorten prompt
`PromptInvalid`	Invalid or rejected prompt	Check prompt format and content

Image/Media Errors

failCode	Description	Solution
`ImageFormatIncorrect`	Incorrect image format	Use JPEG, PNG, or WebP
`InvalidImageSize`	Invalid image dimensions	Check image size requirements
`Upload error`	Image exceeds 10MB limit	Compress image to under 10MB
`INVALID_IMAGE_URL`	Cannot access image URL	Check URL accessibility
`INVALID_LORA_URL`	Cannot download LoRA model	Check LoRA URL

Rate Limiting & Quota

failCode	Description	Solution
`RateLimited`	Rate limited, retry later	Reduce request frequency, wait and retry
`RateLimitExceeded`	Rate limit exceeded	Retry later
`InsufficientQuota`	Insufficient quota	Check account balance

Processing & System Errors

failCode	Description	Solution
`Timeout`	Response timeout	Retry later
`Task TimeOut`	Task expired, generation failed	Switch to another task
`BadRequest`	Missing required parameters	Check request parameters
`MissingParameter`	Missing required parameter	Refer to API docs, add parameter

Error Response Examples

HTTP Error (Immediate Return)

400 - Parameter Error

{
  "code": 400,
  "message": "Prompt exceeds provider limit (max 2000 chars)",
  "data": null
}

401 - Authentication Failed

{
  "code": 401,
  "message": "Invalid or missing API key",
  "data": null
}

429 - Rate Limited

{
  "code": 429,
  "message": "Provider rate limited, please retry later",
  "data": null
}

504 - Timeout

{
  "code": 504,
  "message": "Provider timeout, please retry later",
  "data": null
}

Task Failure (When Querying Status)

Content Violation

{
  "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
  }
}

NSFW Content

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "NSFW",
    "failMsg": "NSFW, Try different input please.",
    "createTime": 1767965610929,
    "completeTime": 1767965652317
  }
}

Image Format Error

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "ImageFormatIncorrect",
    "failMsg": "Image format is incorrect",
    "createTime": 1767965610929,
    "completeTime": 1767965652317
  }
}

Error Handling Best Practices

1. Retry Strategy

Error Type	Retry?	Strategy
`400` (Parameter Error)	No	Fix parameters then retry
`401` (Auth Failed)	No	Check API Key
`429` (Rate Limited)	Yes	Exponential backoff, wait 60s then retry
`500` (Server Error)	Yes	Exponential backoff, max 3 times
`504` (Timeout)	Yes	Wait then retry, max 3 times
Content Violation	No	Modify content then retry
Image Error	No	Fix image then retry

2. Exponential Backoff Example

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. Content Moderation Tips

To avoid content violation errors:

Avoid violence, pornography, politically sensitive content
Check that input images comply with content policy
Use clear, specific descriptions, avoid ambiguous expressions
Test with simple, safe content first

4. Monitoring and Logging

Recommended to log for debugging:

taskId — Unique task identifier
failCode — Failure code
failMsg — Failure message
Request parameters (sanitized)

Provider-Specific Errors

OpenAI

failCode	Description
`SensitiveContentDetected`	Content flagged by OpenAI as violation
`InputImageSensitiveContentDetected`	Images containing real people not supported

MidJourney

failCode	Description
`Website TimeOut`	MidJourney website unresponsive after multiple attempts
`INVALID_TASK_ID`	Invalid previous task ID for upscale/vary

Seedream (ByteDance)

failCode	Description
`outputimagesensitivecontentdetected`	Output image contains sensitive content
`InvalidImageSize`	Invalid image dimensions

FAQ

Q: Got 429 error, how long should I wait?
A: Wait 60 seconds then retry, or use exponential backoff strategy.

Q: How to avoid PromptLengthExceeded error?
A: Each model has different prompt length limits, check the model documentation. Generally keep under 2000 characters.

Q: Can I appeal SensitiveContentDetected error?
A: This is the upstream AI provider's content moderation result. Recommend modifying content and resubmitting.

Q: What should I do with 5xx errors?
A: These are temporary server issues. Use exponential backoff retry, max 3 times. If persistent, contact support.

Q: Why does task status return 200 but state is failed?
A: HTTP 200 means the API request itself succeeded, but task execution failed (e.g., content violation). Actual error info is in failCode and failMsg.

Support

Experiencing persistent errors? Contact support with:

taskId — Failed task ID
failCode — Error code
Request parameters (sanitized)
Error occurrence time

Technical Support: support@apixo.ai

Error Codes

On this page