Errors

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

Response format

All errors return a JSON object with an error field:

{
  "error": "Description of what went wrong"
}

Some endpoints include additional context:

{
  "error": "Invalid variant IDs or variants do not belong to this store",
  "missingVariants": ["variant_123", "variant_456"]
}

Code	Description
`200`	Success
`204`	Success (no content, used for OPTIONS preflight)
`400`	Bad request - invalid or missing parameters
`401`	Unauthorized - authentication failed
`404`	Not found - resource doesn’t exist
`500`	Server error

Error	Cause
`Missing API key`	No `Authorization` header or missing `Bearer` prefix
`Invalid API key format`	Key doesn’t match expected format (`ak_` + 48 hex characters)
`Invalid API key`	Key not found or doesn’t match
`Store is deactivated`	The store associated with this key is inactive
`API key validation failed`	Internal error during validation

Returned when request body is missing required fields or has invalid values:

{
  "error": "Missing required field: items (array of { variantId, quantity })"
}

{
  "error": "Each item must have a positive integer quantity"
}

Returned when the requested resource doesn’t exist or isn’t accessible:

{
  "error": "Product not found"
}

{
  "error": "Collection not found"
}

Returned when something unexpected goes wrong. The error message indicates which operation failed:

{
  "error": "Failed to fetch products"
}