Errors — Pixii API

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