Errors
JSON endpoints
Routes that return JSON (for example GET /api/v1/members or GET /api/v1/members/{id}) use a consistent error object:
{
"code": "UNAUTHORIZED" | "FORBIDDEN" | "BAD_REQUEST" | "NOT_FOUND" | "CONFLICT" | "PRECONDITION_FAILED",
"message": "Human-readable explanation"
}Example bodies by code
Same envelope for every code below: code (machine) + message (human). Success responses on each route are documented under Members, Groups & folders, and Entries.
401: UNAUTHORIZED
{
"code": "UNAUTHORIZED",
"message": "Missing or invalid API key. Use Authorization: Bearer <token>."
}403: FORBIDDEN (insufficient scope; message varies)
{
"code": "FORBIDDEN",
"message": "Missing API key scope: members requires read_write"
}400: BAD_REQUEST
{
"code": "BAD_REQUEST",
"message": "Invalid request body."
}404: NOT_FOUND
{
"code": "NOT_FOUND",
"message": "Member not found."
}409: CONFLICT
{
"code": "CONFLICT",
"message": "Version conflict: member was modified by another client."
}503: PRECONDITION_FAILED
{
"code": "PRECONDITION_FAILED",
"message": "Object storage is not configured. …"
}Codes
| code | HTTP | When |
|---|---|---|
UNAUTHORIZED | 401 | Missing or invalid Authorization: Bearer token |
FORBIDDEN | 403 | Valid key but insufficient scope for the route |
BAD_REQUEST | 400 | Malformed query or path (where validated) |
NOT_FOUND | 404 | Resource missing or not visible (for example GET /api/v1/members/{id} when the member does not exist, is trashed, or belongs to another account) |
CONFLICT | 409 | Optimistic concurrency (for example PATCH /api/v1/members/{id} with a stale expectedVersion) |
PRECONDITION_FAILED | 503 | Required infrastructure missing (for example object storage not configured for markdown image rehost on member about updates) |
Member media endpoint
GET /api/v1/members/{memberId}/media returns bytes, a 302 redirect, or failures without a JSON body in several cases.
- 200: image body;
Content-Typeand optionalETagfrom storage - 302: redirect to a legacy public
httpsURL when the stored value is an embeddable HTTP(S) URL - 400: JSON
BAD_REQUEST(invalidkindor member id) - 401 / 403: same JSON shape as other v1 routes
- 404: empty body (unknown member, deleted member, missing asset, or non-embeddable URL)
- 503: empty body when object storage (MinIO) is not configured