> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Complete API error code reference and troubleshooting guide

## Overview

APIXO API uses two layers of error information:

1. **HTTP Status Codes** — Returned immediately when request fails
2. **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`:

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

### 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**

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

**401 - Authentication Failed**

```json theme={null}
{
  "code": 401,
  "message": "Invalid or missing API key",
  "data": null
}
```

**402 - Insufficient Quota**

```json theme={null}
{
  "code": 402,
  "message": "Insufficient quota. Please check your account balance.",
  "data": null
}
```

**429 - Rate Limited**

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

**504 - Timeout**

```json theme={null}
{
  "code": 504,
  "message": "Provider timeout, please retry later",
  "data": null
}
```

### Task Failure (When Querying Status)

**Content Violation**

```json theme={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
  }
}
```

**NSFW Content**

```json theme={null}
{
  "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**

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

**Transient Upstream Error**

```json theme={null}
{
  "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

<Tip>
  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`.
</Tip>

### 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

```javascript theme={null}
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

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

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](mailto:support@apixo.ai)