Errors

When a request fails, the API returns a JSON error body with a consistent structure.

Error format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable description of the error."
  }
}

Code	HTTP Status	Description
`BAD_REQUEST`	400	Malformed request (e.g. invalid JSON body)
`UNAUTHENTICATED`	401	Missing or invalid API key
`FORBIDDEN`	403	The API key lacks the required permission
`NOT_FOUND`	404	The requested resource does not exist
`CONFLICT`	409	A request with the same `Idempotency-Key` is already in progress
`VALIDATION_ERROR`	422	The request body or parameters failed validation
`RATE_LIMITED`	429	Rate limit exceeded for this API key
`INTERNAL_ERROR`	500	An unexpected server error occurred

Missing authentication:

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Authorization header is required."
  }
}

Insufficient permissions:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have the inventory:read permission."
  }
}

Validation failure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'email' is required."
  }
}