Skip to main content

Errors

The HTTP status codes returned by the ZENTRA Cloud v5 API — 401, 403, 422, and 429 — what causes each, and how to handle them.

Errors

The v5 API uses standard HTTP status codes. A 2xx status means success; 4xx means the request was rejected. This article is the canonical reference — endpoint articles link here and note any endpoint-specific causes.

Common errors

Status

Meaning

Typical cause

401 Unauthorized

The request lacks a valid API key.

Missing or invalid X-API-Key header.

403 Forbidden

You are not a member of the requested organization.

Passing an organization_id you have no membership in.

422 Unprocessable Entity

The request parameters are invalid.

Out-of-range or unrecognized parameter values (e.g. page_num < 1, limit outside 1–1000, or an unrecognized expand value).

429 Too Many Requests

Per-user rate limit exceeded.

Too many requests in the rate-limit window. See Rate Limiting.

Notes on specific statuses

401 vs. 403. A 401 means the key itself is missing or invalid. A 403 means the key is valid but isn't authorized for what you asked — for example, filtering List Devices by an organization_id you don't belong to. Membership questions return 403, never a silently empty 200, so you can distinguish "no access" from "access, but nothing there."

422 is returned before any lookup. Invalid parameters are rejected up front, so a 422 never partially processes a request. The response identifies the offending parameter.

Empty results are not errors. If your memberships grant access to no matching devices, the response is still 200 OK with an empty array and a valid pagination block — not a 4xx. See the List Devices empty-result example.

Handling errors

  • 401 — check that the X-API-Key header is present and current. If you recently regenerated your token, update it. See API Token.
  • 403 — confirm your organization membership and role. Data access requires an Administrator, Editor, or User role in the owning organization.
  • 422 — read the response body; it names the invalid parameter. Fix the value and retry.
  • 429 — back off and retry after the rate-limit window. See Rate Limiting.

How did we do?

Rate Limiting

List Devices

Contact