Error Handling

Response format

Xenia does not wrap responses in a status/statusCode envelope. The HTTP status code carries success/failure, and the body shape depends on the endpoint. There is no requestId field.

Success responses

The exact shape depends on the endpoint, but it is always one of these: List / query endpoints (e.g. task catalog, submission records):

{
  "data": [ /* rows */ ],
  "meta": { "total": 128, "totalCount": 128 }
}

Action / write endpoints (e.g. delete user, change role):

{
  "data": {},
  "extra_meta": { "message": "User Deleted successfully" }
}

User context / login:

{
  "data": { /* ... */ },
  "message": "Login Successfully",
  "extra_meta": { "token": "..." }
}

Successful writes return HTTP 200, not 201. Read the HTTP status code — do not look for a status: true or statusCode field, they do not exist.

Error responses

Errors return a non-2xx HTTP status with one of these bodies:

{ "status": false, "code": 401, "error": { "message": "Invalid client credentials", "data": null } }

{ "error": { "message": "Description of what went wrong", "meta": {} } }

Always branch on the HTTP status code, then read error.message for detail.

HTTP status codes

Code	Meaning	Typical cause
`200`	OK	Request succeeded (including successful writes)
`400`	Bad Request	Missing/invalid field, invalid UUID, malformed JSON
`401`	Unauthorized	Missing/invalid credentials, or `x-client-user` not in the key’s workspace
`403`	Forbidden	Route not allow-listed for API keys, or the key’s user lacks the required permission
`404`	Not Found	Wrong path, or resource in a different workspace
`409`	Conflict	A concurrent write to the same workspace record won the race (bulk location-attribute writes). Re-read and retry
`422`	Unprocessable Entity	Request body or path failed schema validation — wrong type, unknown field, array over its size cap. Body is `{ "error": { "error": "...", "message": "...", "meta": {} } }`
`500`	Internal Server Error	Server-side error
`504`	Gateway Timeout	Query ran past the ~60s load-balancer limit — narrow the date range / add filters / page

There is no general request rate limiter on the API, so you will not normally see 429. Very large unfiltered queries fail with a 504 from the load balancer at ~60 seconds rather than a timeout body — always scope reporting queries with a date range and page large result sets.

Common errors & solutions

401 — Invalid client credentials

{ "status": false, "code": 401, "error": { "message": "Invalid client credentials" } }

The x-client-key / x-client-secret pair is wrong, or the key was deactivated. Re-check the values or create a new key.

Two related 401s: User not found in the workspace (the x-client-user you passed isn’t a member of the key’s workspace) and Client does not belong to this workspace (the {workspaceId} in the path doesn’t match the key’s workspace).

curl -X GET "https://api.xenia.team/api/v1/mgt/user-context" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

(Workspace is derived from the key — you don’t need a workspace-id header unless the path contains {workspaceId}.)

403 — Forbidden

Two distinct cases share this status:

Route not allow-listed for API keys:
{ "status": false, "code": 403, "error": { "message": "Forbidden: API key not authorized for this route" } }
The endpoint you called isn’t part of the API-key surface. Only the endpoints in this API Reference are reachable with a client key — check the path and method.
Permission denied for the key’s user: the route is allow-listed, but the key’s default user lacks the permission it requires (e.g. CAN_VIEW_REPORTING, CAN_MANAGE_USERS). Assign the key a default user whose role grants the needed access.

404 — Not Found

Double-check the path (note reads and reports live under /api/v1/ops/..., user/grid/schedule endpoints under /api/v1/mgt/...) and that the resource ID belongs to the key’s workspace.

400 — Bad Request

{ "error": { "message": "Task title is required", "meta": {} } }

A required field is missing or a value is malformed (bad UUID, invalid date). Review the endpoint’s request schema.

504 — Gateway Timeout

The query didn’t finish within ~60 seconds at the load balancer. Add a fromDate/toDate range, other filters, or page the results with offset/limit.

Best practices

Branch on HTTP status, then read `error.message`

const response = await fetch(url, options);
if (!response.ok) {
  const err = await response.json().catch(() => ({}));
  console.error(`HTTP ${response.status}: ${err?.error?.message ?? 'request failed'}`);
  return;
}
const { data } = await response.json();

Validate UUIDs before sending

const isUUID = (id) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id);

Scope large queries

Always send a date range and page results to stay under the ~60s limit:

{ "fromDate": "2026-01-01", "toDate": "2026-01-31", "offset": 0, "limit": 5000 }

Use meta.totalCount from the response to know when to stop paging.

Getting help

If you encounter persistent errors, gather the request endpoint + method, the full error.message, and your request payload (without secrets), then contact support@xenia.team.

Getting Started

Workflows

Integrations

Response format

Success responses

Error responses

HTTP status codes

Common errors & solutions

401 — Invalid client credentials

403 — Forbidden

404 — Not Found

400 — Bad Request

504 — Gateway Timeout

Best practices

Branch on HTTP status, then read `error.message`

Validate UUIDs before sending

Scope large queries

Getting help

Next steps

Authentication

Data Extraction

​Response format

​Success responses

​Error responses

​HTTP status codes

​Common errors & solutions

​401 — Invalid client credentials

​403 — Forbidden

​404 — Not Found

​400 — Bad Request

​504 — Gateway Timeout

​Best practices

​Branch on HTTP status, then read error.message

​Validate UUIDs before sending

​Scope large queries

​Getting help

​Next steps

Authentication

Data Extraction

Response format

Success responses

Error responses

HTTP status codes

Common errors & solutions

401 — Invalid client credentials

403 — Forbidden

404 — Not Found

400 — Bad Request

504 — Gateway Timeout

Best practices

Branch on HTTP status, then read `error.message`

Validate UUIDs before sending

Scope large queries

Getting help

Next steps