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
`400`	Bad request
`401`	Unauthorized, missing or invalid API key
`402`	Payment required, insufficient credits or plan does not allow
`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
`INVALID_IMAGE`	400	An image is not a public http(s) URL or valid base64 bytes	Send a public URL, or PNG, JPEG or WebP bytes under 10 MB
`UNSUPPORTED_DELIVERABLE`	400	A deliverable, platform, format or reference combination is not supported	Check the `detail` field; it names the entry and the allowed values
`NO_ACTIVE_BRAND`	400	No active brand found for your organization	Set up a brand in your Pixii dashboard before making API requests
`BRAND_NOT_FOUND`	404	No active brand with this `brand_id` in your organization	Pick an id from `GET /v2/api/brands`
`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
`SUBSCRIPTION_PAUSED`	402	Your subscription is paused	Resume it from Pixii settings
`PAID_PLAN_REQUIRED`	402	A+ Content or Scale on the free plan	Upgrade your plan
`PLAN_LIMIT_REACHED`	402	More than one product per Scale run requires the Scale plan	Send one product, or upgrade to the Scale plan
`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 error object (when an entire job fails and its credits are refunded in full) or as a visual with status: "failed" (when an individual visual fails inside an otherwise completed job and that visual is refunded).

Code	Description	How to fix
`PRODUCT_NOT_FOUND`	The product is not in your Pixii account	Generate something for it first, or check `product_id`, `asin` and `country_code`
`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
`NO_VISUALS_FOUND`	The product has no completed visuals to download	Generate visuals for the product first
`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 visuals	Credits for failed visuals are automatically refunded. Retry the request
`PROCESSING_ERROR`	Unable to process the request	Retry the request. Contact support if this persists

Validation error json

{
"success": false,
"data": null,
"error": {
  "code": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "detail": "product: country_code is required with asin"
}
}

Rate limit error json

{

"success": false,
"data": null,
"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
}
}

Failed job json

{

"success": true,
"data": {
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"job_type": "create_listing",
"status": "failed",
"credit_cost": 70,
"credits_refunded": 70,
"error": {
"code": "PRODUCT_FETCH_ERROR",
"message": "Unable to fetch product data. Please verify the ASIN and try again"
},
"output": null
},
"error": null
}