Errors

The Products Manager 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": "validation_error",
  "message": "The EAN field is required.",
  "details": {
    "ean": ["This field is required."]
  }
}

Field	Description
`error`	Machine-readable error code
`message`	Human-readable description
`details`	Optional field-level validation errors

Status	Meaning
`200 OK`	Request succeeded
`201 Created`	Resource created successfully
`204 No Content`	Request succeeded, no body returned
`400 Bad Request`	Invalid request parameters
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	Insufficient permissions
`404 Not Found`	Resource not found
`409 Conflict`	Resource already exists (e.g. duplicate EAN)
`422 Unprocessable Entity`	Validation error
`429 Too Many Requests`	Rate limit exceeded — see Rate Limiting
`500 Internal Server Error`	Unexpected server error

Error code	Description
`authentication_required`	No API key provided
`invalid_api_key`	API key is invalid or revoked
`permission_denied`	Key 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

For 429 errors, check the Retry-After response header for the number of seconds to wait before retrying.