API errors and rate limits

Content API errors use a stable JSON shape, machine code, and correlation_id.

Error shape

json

{
  "error": "Human-readable message",
  "code": "RATE_LIMITED",
  "correlation_id": "uuid"
}

HTTP	Code	What to do
400	INVALID_QUERY_PARAMS	Fix query params.
401	MISSING_TOKEN / INVALID_TOKEN / TOKEN_EXPIRED	Check bearer token and rotation.
403	TOKEN_PROJECT_MISMATCH / PROJECT_NOT_ENTITLED	Check project, plan, and billing state.
404	CONTENT_NOT_FOUND	Check ID or content item state.
429	RATE_LIMITED	Use Retry-After and wait for reset.

1000 requests per day per project.
Window is counted by UTC day.
Countable responses are 200, 304, 400, and 404 after auth/project/entitlement gates.
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After for 429.

Build list/detail sync first, then add cache and retry.