Response envelope

Success

{
  "success": true,
  "message": "OK",
  "data": { ... }
}

Paginated list

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "last_page":    4,
    "per_page":     15,
    "total":        56
  }
}

Error

{
  "success": false,
  "message": "Human-readable description",
  "errors":  { "field": ["Validation message"] },
  "code":    "machine_readable_code"
}

HTTP status codes

Status	When
200	Success
201	Resource created (e.g. webhook subscription)
401	Missing or expired authentication token
403	Token lacks required ability, or ownership check failed
404	Resource not found, or role-filtered article not visible to caller
422	Validation error — check errors field for field-level messages
429	Rate limit exceeded — slow down (60 req/min)
500	Server error — please contact support with the request ID

Rate limiting

All API routes apply the throttle:api middleware:

• 60 requests per minute per authenticated user
• 60 requests per minute per IP address (unauthenticated)

When exceeded, the response is 429 Too Many Requests with a Retry-After header indicating when the limit resets. No data body is returned.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

Pagination parameters

Paginated endpoints accept these query parameters:

Parameter	Default	Description
page	1	Page number (1-indexed)
per_page	15	Results per page (max 100)

Error codes reference

code	HTTP	Meaning
unauthenticated	401	No valid token
insufficient_token_ability	403	Token lacks required ability
bid_too_low	422	Bid amount does not exceed current bid + minimum increment
auction_closed	422	Lot/auction is not currently open for bidding
bidder_not_verified	403	Bidder verification tier does not allow this bid amount
deposit_required	403	Bid deposit not registered for this auction
media_not_owned	403	Media is attached to a lot/auction you do not own
rate_limited	429	60 request/minute limit exceeded