Errors

Error response shape, HTTP status codes and the full Pixii error code reference.

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
`201`	Resource created successfully
`202`	Job accepted and queued for processing
`400`	Bad request
`401`	Unauthorized — missing or invalid API key
`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
`UNAUTHORIZED`	401	Missing or invalid API key	Check your API key is correct and has not been revoked
`VALIDATION_ERROR`	400	One or more request parameters are invalid	Check the `detail` field for which parameters failed and why
`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
`INSUFFICIENT_CREDITS`	400	Not enough credits to process this request	Top up your credits from your dashboard
`NO_ACTIVE_BRAND`	422	No active brand found for your organization	Set up a brand in your Pixii dashboard before making API requests
`JOB_NOT_FOUND`	404	Job not found	Check the job ID is correct and belongs to your organization
`PROCESSING_ERROR`	500	Unable to process the request	Retry the request. Contact support if this persists
`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

Validation error json

{
"success": false,
"error": {
  "code": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "detail": "asin: ASIN should be minimum 5 characters long"
}
}

Rate limit error json

{

"success": false,
"error": {
"code": "RATE_LIMIT_MINUTE_EXCEEDED",
"message": "Per-minute rate limit exceeded. Please wait before sending more requests",
"detail": "Per-minute rate limit exceeded. Try again in 47 seconds",
"retry_after": 47
}
}