Errors & Pagination

Two conventions hold across the whole API: every error has the same shape, and every list endpoint paginates the same way.

Error shape

All 4xx responses return the same two-field body:

{
  "code": "NOT_FOUND",
  "message": "The requested resource does not exist."
}

code is stable and machine-readable — branch on it, not on message.

Status	Code	Returned by
401	INVALID_CREDENTIALS	POST /auth/login with wrong credentials
404	NOT_FOUND	Any {id} route when the resource does not exist
409	ORDER_ALREADY_SHIPPED	POST /orders/{orderId}/cancel after shipping
422	VALIDATION_FAILED	POST /products, POST /orders with an invalid body

404 is also what you get for a resource that exists but belongs to another account — the API does not reveal which of the two it is.

Pagination

List endpoints (GET /products, GET /orders) take the same two query parameters:

Parameter	Default	Max
page	1	—
pageSize	20	100

And return the same envelope around items:

{
  "items": [ … ],
  "page": 1,
  "pageSize": 20,
  "total": 68
}

Iterate until page * pageSize >= total. Requesting a page past the end returns an empty items array, not an error.