Pixii uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error with the information provided. Codes in the `5xx` range indicate an error with Pixii’s servers.

## Error response format

All errors return a consistent JSON body:

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Machine-readable error code. Use this to handle specific errors in your code |
| `message` | string | Human-readable description of the error |
| `detail` | string or null | Additional context about what went wrong. Present on validation errors and rate limit errors |

Rate limit errors include an additional `retry_after` field.

## HTTP status codes

| Status | Meaning |
| --- | --- |
| `200` | Request succeeded |
| `400` | Bad request |
| `401` | Unauthorized — missing or invalid API key |
| `402` | Payment required — insufficient credits |
| `404` | Resource not found |
| `429` | Too many requests — rate limit exceeded |
| `500` | Internal server error |
| `503` | Service temporarily unavailable |

## API errors

Returned in the top-level `error` envelope on a non-2xx HTTP response.

| Code | HTTP | Description | How to fix |
| --- | --- | --- | --- |
| `VALIDATION_ERROR` | 400 | One or more request parameters are invalid | Check the `detail` field for which parameters failed and why |
| `NO_ACTIVE_BRAND` | 400 | No active brand found for your organization | Set up a brand in your Pixii dashboard before making API requests |
| `UNAUTHORIZED` | 401 | Missing or invalid API key | Check your API key is correct and has not been revoked |
| `INSUFFICIENT_CREDITS` | 402 | Not enough credits to process this request | Top up your credits from your dashboard |
| `JOB_NOT_FOUND` | 404 | Job not found | Check the job ID is correct and belongs to your organization |
| `RATE_LIMIT_MINUTE_EXCEEDED` | 429 | Too many requests in the current minute | Wait the number of seconds in `retry_after` before retrying |
| `RATE_LIMIT_DAY_EXCEEDED` | 429 | Daily request limit reached | Wait until tomorrow or check `retry_after` for exact reset time |
| `INTERNAL_ERROR` | 500 | An unexpected error occurred | Retry the request. Contact support if this persists |
| `SERVICE_UNAVAILABLE` | 503 | Service is temporarily unavailable | Wait a few minutes and retry |

## Job errors

Job errors are returned inside a successful (`200`) job payload — they have no HTTP status. They appear either as the job’s top-level `error_code` (when an entire job fails) or as `ads[].error.code` (when an individual image fails inside an otherwise-completed job).

| Code | Description | How to fix |
| --- | --- | --- |
| `PRODUCT_FETCH_ERROR` | Unable to fetch product data for the given ASIN | Verify the ASIN is correct and available on the target marketplace |
| `PRODUCT_NOT_AVAILABLE` | Product data is not available or invalid | The ASIN exists but product data could not be retrieved — try a different ASIN |
| `PRODUCT_ANALYSIS_ERROR` | Failed to analyze product data | Retry the request. Contact support if this persists |
| `CONTENT_MODERATION_ERROR` | Content was flagged by moderation | The product or images were flagged — try different images or contact support |
| `IMAGE_GENERATION_ERROR` | Failed to generate one or more images | Credits for failed images are automatically refunded. Retry the request |
| `PROCESSING_ERROR` | Unable to process the request | Retry the request. Contact support if this persists |