Error Codes

Error format

{
  "error": {
    "code": "validation_error",
    "message": "Field 'title' is required"
  }
}

HTTP status codes

Code	Meaning	When
400	Bad Request	Validation error, malformed request
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn’t exist
409	Conflict	Duplicate resource (e.g., email already registered)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error

Common error codes

Code	Description
validation_error	Request body failed validation
unauthorized	Missing or invalid auth token
forbidden	Insufficient scopes/permissions
not_found	Resource not found
already_exists	Resource already exists (e.g., duplicate email)
rate_limited	Too many requests
payment_error	Payment processing failed
shipping_error	Shipping rate calculation failed
inventory_error	Insufficient stock
email_verification_required	Email must be verified before action
account_requires_password_reset	Imported account needs password reset

Rate limit headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

Validation errors

Validation errors include field-level details:

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": [
      { "field": "email", "message": "Invalid email format" },
      { "field": "price", "message": "Must be greater than 0" }
    ]
  }
}