Skip to main content

HTTP Status Codes

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

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. If you are looking for sensor errors, see Device & Sensor Error Codes.

Common errors

Status

Meaning

Typical cause

401 Unauthorized

The request lacks a valid API key.

Missing or invalid X-API-Key header.

403 Forbidden

Your key is valid but not authorized for this request.

Passing an organization_id you have no membership in, or reading data from a device where your role is below User (for example, Viewer).

404 Not Found

The device could not be found for your key.

An unknown device ID, or a device outside the workspaces you can reach when you have workspace-only access.

422 Unprocessable Entity

The request parameters are invalid.

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

429 Too Many Requests

Rate limit exceeded for this endpoint's budget.

Too many requests in the rate-limit window. The Retry-After header says how many seconds to wait. 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, or reading data from a device where you are a Viewer. Membership questions return 403, never a silently empty 200, so you can distinguish "no access" from "access, but nothing there." To check data access before calling Get Device Readings, use the can_read_data field in List Devices.

404 for devices. A 404 from Get Device Readings means the device could not be found for your key. If you have workspace-only access in an organization, devices outside your workspaces also return 404, so a 404 does not always mean the serial number is wrong.

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; check can_read_data in List Devices.
  • 404 — confirm the device ID against List Devices. If the device isn't listed, it isn't shared with you.
  • 422 — read the response body; it names the invalid parameter. Fix the value and retry.
  • 429 — wait the number of seconds in the Retry-After header, then retry. See Rate Limiting.

How did we do?

Rate Limiting

Device & Sensor Error Codes

Contact