---
title: "HTTP Status Codes"
description: "The HTTP status codes returned by the ZENTRA Cloud v5 API — 401, 403, 422, and 429 — what causes each, and how to handle them."
url: "https://docs.zentracloud.io/l/en/article/ajte070y7e-errors"
category: "v5.0"
updated_at: "2026-11-05T19:48:04Z"
language: "en"
---

# HTTP Status Codes

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](/l/en/article/l1uopg3wo7-device-sensor-error-codes).

[Handle HTTP status codes | ZENTRA Cloud](https://www.youtube.com/embed/tSStmU3fx18?feature=oembed)

#### 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` &lt; 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](/l/en/article/f6wdg770d3-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](/l/en/article/7t31rdmwh4-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 Data, use the `can_read_data` field in List Devices.

**404 for devices.** A `404` from Get Device Data 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](/l/en/article/7t31rdmwh4-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](/l/en/article/xot1qptzgz-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](/l/en/article/f6wdg770d3-rate-limiting).
