Errors

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

Error response format

Most error responses follow this unified envelope:

{
  "error": {
    "code": 404,
    "error_code": "PRODUCT_NOT_FOUND",
    "type": "not_found",
    "message": "The EAN field is required.",
    "details": null,
    "path": "/api/v1/products/550e8400-e29b-41d4-a716-446655440000",
    "request_id": "abc-123",
    "timestamp": "2026-09-17T10:30:00Z"
  }
}

Divergent shapes — endpoints that don't use the envelope above

A handful of error sources predate the unified envelope and were deliberately not rewritten to avoid silently changing an already-integrated contract. Match on the field names below, not on error.code:

HTTP status codes

Dependency not configured (409)

Some operations depend on something an administrator sets up per instance: an Odoo connection, a connector's webhook secret, an AI provider assigned to a usage, the shared key of the price monitoring service, the optional vector search engine. When that setup is missing, the API answers 409 Conflict with an error_code from the *_NOT_CONFIGURED family. This is a permanent state of the instance, not an outage: retrying will not help, fixing the configuration will. error.details names the dependency and the fix.

{
  "error": {
    "code": 409,
    "error_code": "ODOO_NOT_CONFIGURED",
    "type": "conflict",
    "message": "No Odoo connection is configured on this instance. Enter the Odoo URL, database and credentials in the Odoo Sync screen before running this import.",
    "details": { "dependency": "odoo", "how_to_fix": "Renseignez l'URL, la base et les identifiants Odoo dans l'écran Odoo Sync (/odoo-sync)" },
    "path": "/api/v1/brands/import-from-odoo",
    "request_id": "abc-123",
    "timestamp": "2026-09-18T10:30:00Z"
  }
}

Validation errors (422)

Field-level validation failures populate error.details as an array:

{
  "error": {
    "code": 422,
    "error_code": "VALIDATION_FAILED",
    "type": "validation_error",
    "message": "Request validation failed",
    "details": [
      { "field": "body.name", "message": "Field required", "type": "missing" }
    ],
    "path": "/api/v1/products",
    "request_id": "abc-123",
    "timestamp": "2026-09-17T10:30:00Z"
  }
}

Common error codes

Public API families (/ext, /windev)

Error responses of /api/v1/ext/* and /api/v1/windev/* (missing or refused key, not found, validation, quota, server error) carry the API-Version: 1 header — and the deprecation headers when the operation is deprecated — like their successful responses. The body is the envelope above; nothing else changes. A refusal returned directly by a middleware (module gate, license, CSRF) may come without these headers: the HTTP status is enough. See External API → Versioning.

Localization

error.message is translated based on the Accept-Language header. Only French (fr) and English (en) have translated message catalogs today, even though the underlying locale middleware accepts a broader set of locales for other purposes.

curl https://api.pixeepim.com/api/v1/products/00000000-0000-0000-0000-000000000000 \
  -H "Authorization: Bearer {api_key}" \
  -H "Accept-Language: fr"

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:

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