Error Codes - APIXO

Overview

APIXO API uses two layers of error information:

HTTP Status Codes — Returned immediately when request fails
Failure Codes — Returned as failCode for failed tasks, or as a provider error identifier for some immediate errors

┌─────────────────────────────────────────────────────────────┐
│                      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 ──→ Failure Code                  │
│                               (failCode/failMsg)             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Type	When Triggered	Meaning	Example
HTTP Status Code	Immediately on request	Request itself has issues	`401` Invalid API Key
Failure Code	Immediate error response or task status query	Specific provider or validation failure	`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
`502`	Bad Gateway	Upstream provider error	Retry later
`503`	Service Unavailable	Service temporarily unavailable	Retry later
`504`	Gateway Timeout	Provider timeout	Retry later

Failure Codes

When an async task fails, the status 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."
  }
}

Some immediate HTTP errors may use the same normalized codes and return the HTTP status shown in the tables below.

The same failCode can appear with slightly different failMsg text depending on the upstream provider. Use failCode for programmatic handling and show failMsg to support/debugging tools.

Content Policy and Safety

failCode	Usually returned with	Common meaning	What to do
`SensitiveContent`	`400`	Prompt or media violates provider policy	Adjust the prompt or media
`SensitiveContentDetected`	`400`	Content was flagged by a provider moderation system	Rewrite the prompt or use safer inputs
`InputImageSensitiveContentDetected`	`400`	Input image contains restricted or unsupported content	Use a different image
`InputOutputSensitiveContentDetected`	`400`	Input or generated output was flagged as sensitive	Try different input content
`ProhibitedContentDetected`	`400`	Provider rejected prohibited content	Try a different prompt or media
`NSFW`	`400`	NSFW content detected	Use policy-compliant content
`CopyrightFailed`	`400`	Prompt, image, or output may violate copyright restrictions	Remove copyrighted artist/style references or use different media

Prompt and Parameter Validation

failCode	Usually returned with	Common meaning	What to do
`PromptLengthExceeded`	`400`	Prompt exceeds provider length limits	Shorten the prompt
`PromptInvalid`	`400`	Prompt is invalid, rejected, or incompatible with the selected mode/model	Check model docs and simplify the input
`InvalidPromptParameter`	`400`	Prompt-related parameter is invalid or unsupported	Check accepted values for the model
`MissingParameter`	`400`	One or more required request parameters are missing	Add the required field listed in the API docs
`BadRequest`	`400`	Request body is malformed or missing required fields	Validate request JSON and required parameters
`Validation error`	`400`	Upstream provider rejected request validation	Check parameters and model constraints
`ParameterError`	`400`	A numeric or format constraint was not met	Adjust the parameter to the allowed range
`RatioError`	`400`	Aspect ratio is invalid or unsupported	Use a supported ratio

Image, Video, and Media Inputs

failCode	Usually returned with	Common meaning	What to do
`ImageFormatIncorrect`	`400`	Image format or MIME type is unsupported	Use a supported image format such as JPEG, PNG, or WebP
`ImageSizeIncorrect`	`400`	Image file size or pixel count is outside limits	Resize or compress the image
`InvalidImageSize`	`400`	Image dimensions do not meet model requirements	Check the model’s image size requirements
`ImageNotAccess`	`400`	Image URL cannot be fetched or image source is empty	Use a reachable image URL
`ImageInvalid`	`400`	Image was rejected by the provider	Try a different image
`ImageIncorrect`	`400`	Image is duplicated, incompatible, or restricted	Try different source media
`InputFormatIncorrect`	`400`	Input media format, resolution, or pixel count is unsupported	Convert or resize the media
`Upload error`	`400`	Uploaded media exceeds upload constraints, commonly 10MB	Compress or resize the upload
`VideoIncorrect`	`400`	Video contains unsupported content such as real-person footage	Use a different video
`VideoInvalid`	`400`	Video duration, resolution, or visible subject requirements are not met	Check the model’s video requirements
`InputIncorrect`	`400`	Input duration or shape is invalid for the model	Adjust the input to the documented limits
`INVALID_IMAGE_URL`	`400`	Cannot access image URL	Check URL accessibility
`INVALID_LORA_URL`	`400`	Cannot download LoRA model	Check LoRA URL

Authentication, Quota, and Rate Limits

failCode	Usually returned with	Common meaning	What to do
`AppAuthFailed`	`401`	Provider authentication failed	Contact support if your APIXO key is valid
`InsufficientQuota`	`402`	Account quota is insufficient	Check account balance or quota
`InsufficientBalance`	`402`	Provider balance is insufficient	Top up balance or contact support
`RateLimited`	`429`	Provider rate limited the request	Wait and retry with backoff
`RateLimitExceeded`	`429`	API or provider rate limit exceeded	Reduce request frequency and retry later
`Timeout`	`504`	Provider request timed out	Retry with backoff

Upstream and Processing Failures

failCode	Usually returned with	Common meaning	What to do
`CreateTaskFailed`	`400`	Task could not be created by the upstream provider	Retry later or adjust input
`StreamError`	`400`	Streaming response failed	Retry later
`UpstreamInternalError`	`400`, `500`	Provider is temporarily unavailable, overloaded, or returned an internal error	Retry later or route to another model
`UpstreamError`	`400`	Upstream response was invalid or failed unexpectedly	Retry later; contact support if persistent
`UpstreamResultError`	`400`	Result could not be fetched from upstream provider	Retry later
`Website TimeOut`	`400`	Provider website did not respond in time	Retry later
`Task TimeOut`	`400`	Task expired or is outdated	Create a new task
`INVALID_TASK_ID`	`400`	Previous task ID is invalid for the requested action	Check the original task ID

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
}

402 - Insufficient Quota

{
  "code": 402,
  "message": "Insufficient quota. Please check your account balance.",
  "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
  }
}

Transient Upstream Error

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "UpstreamInternalError",
    "failMsg": "Request temporarily unavailable, please try again later.",
    "createTime": 1767965610929,
    "completeTime": 1767965652317
  }
}

Error Handling Best Practices

For immediate HTTP errors, retry only transient statuses such as 429, 500, 502, 503, and 504. For task failures, retry only transient failCode values such as RateLimited, RateLimitExceeded, Timeout, CreateTaskFailed, StreamError, UpstreamInternalError, UpstreamError, UpstreamResultError, and Website TimeOut.

1. Retry Strategy

Error Type	Retry?	Strategy
`400` (Parameter Error)	No	Fix parameters then retry
`401` (Auth Failed)	No	Check API Key
`402` (Insufficient Funds)	No	Check balance or quota
`429` (Rate Limited)	Yes	Exponential backoff, wait 60s then retry
`500` (Server Error)	Yes	Exponential backoff, max 3 times
`502` / `503` (Provider Unavailable)	Yes	Exponential backoff, max 3 times
`504` (Timeout)	Yes	Wait then retry, max 3 times
Transient task failure	Yes	Retry only known transient `failCode` values
Content Violation	No	Modify content then retry
Parameter or media validation error	No	Fix input 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

Content moderation is handled by upstream AI providers. Violations cannot be appealed through APIXO — modify your content and resubmit.

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 status query succeeded, but task execution failed. Use failCode and failMsg for the actual failure reason.

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

​Overview

​HTTP Status Codes

​Failure Codes

​Content Policy and Safety

​Prompt and Parameter Validation

​Image, Video, and Media Inputs

​Authentication, Quota, and Rate Limits

​Upstream and Processing Failures

​Error Response Examples

​HTTP Error (Immediate Return)

​Task Failure (When Querying Status)

​Error Handling Best Practices

​1. Retry Strategy

​2. Exponential Backoff Example

​3. Content Moderation Tips

​4. Monitoring and Logging

​Provider-Specific Errors

​OpenAI

​MidJourney

​Seedream (ByteDance)

​FAQ

​Support

Overview

HTTP Status Codes

Failure Codes

Content Policy and Safety

Prompt and Parameter Validation

Image, Video, and Media Inputs

Authentication, Quota, and Rate Limits

Upstream and Processing Failures

Error Response Examples

HTTP Error (Immediate Return)

Task Failure (When Querying Status)

Error Handling Best Practices

1. Retry Strategy

2. Exponential Backoff Example

3. Content Moderation Tips

4. Monitoring and Logging

Provider-Specific Errors

OpenAI

MidJourney

Seedream (ByteDance)

FAQ

Support