API v1

Errors & responses

Response envelopes, error codes, and HTTP status mapping.

Success responses

json

{
  "data": { },
  "meta": { "totalCount": 42, "limit": 50, "offset": 0 }
}

meta is optional — list endpoints include pagination; write endpoints return 201 with the created resource in data.

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": { }
  }
}

HTTP	Code	When
400	VALIDATION_ERROR	Invalid query params or request body
401	UNAUTHORIZED	Missing or invalid token
403	FORBIDDEN	Insufficient scope (e.g. read token on write)
404	NOT_FOUND	Resource not in this organization
500	INTERNAL_ERROR	Unexpected server error
503	SERVICE_UNAVAILABLE	Database not configured