Errors

The Pixee PIM API uses standard HTTP status codes and returns structured JSON error responses when something goes wrong.

Error response format

All error responses follow this structure:

Error response

{
  "detail": "The EAN field is required.",
  "error_code": "VALIDATION_ERROR",
  "timestamp": "2026-05-14T10:30:00Z"
}

Field	Description
`detail`	Human-readable description of the error
`error_code`	Optional machine-readable error code
`timestamp`	ISO 8601 timestamp of when the error occurred

HTTP status codes

Status	Meaning
`200 OK`	Request succeeded
`201 Created`	Resource created successfully
`202 Accepted`	Request accepted — async processing started
`204 No Content`	Request succeeded, no body returned
`400 Bad Request`	Invalid request parameters
`401 Unauthorized`	Missing, invalid, or expired credential
`403 Forbidden`	Insufficient scope or permissions
`404 Not Found`	Resource not found
`409 Conflict`	Resource already exists (e.g. duplicate EAN)
`422 Unprocessable Entity`	Validation error on request body
`423 Locked`	Account locked after repeated failed login attempts
`429 Too Many Requests`	Rate limit exceeded — see Rate Limiting
`500 Internal Server Error`	Unexpected server error
`503 Service Unavailable`	Temporary outage or maintenance

Common error codes

Error code	Description
`AUTHENTICATION_REQUIRED`	No credential provided
`INVALID_API_KEY`	API key is invalid or revoked
`PERMISSION_DENIED`	Credential does not have access to this resource
`NOT_FOUND`	The requested resource does not exist
`VALIDATION_ERROR`	One or more fields failed validation
`DUPLICATE_EAN`	A product with this EAN already exists
`RATE_LIMIT_EXCEEDED`	Too many requests — retry after the indicated delay
`IMPORT_FAILED`	Import job encountered errors — check the error report
`ACCOUNT_LOCKED`	Too many failed login attempts — try again later

Async operations

Endpoints that start long-running jobs (imports, exports, enrichment) return 202 Accepted immediately. Poll the job's status endpoint until the status is completed or failed:

202 Accepted

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

For 429 errors, check the retry_after_seconds field in the response body for the number of seconds to wait before retrying.