Skip to content
Szenera DeveloperDocs
Getting started › If you get stuck › When the first call fails
Chapters

When the first call fails

401, 403, 404, 422, 429, and network errors on the first call: what the code means and which page shows the way back.

6 minute readGetting startedUpdated: 10/25/2026

On this page

Before you start

For
Developers whose first call does not answer with 200
Prerequisite
the complete error response (status, headers, body), for example from curl -sSi

The symptoms are listed in the order in which they most often occur on the first call. Read the status first, then the field code in the error body, and keep the traceId in case you have to ask for help.

Symptoms by frequency

401 with Auth.Required

Meaning: The Authorization header is missing, the word Bearer before it is missing, or the value has no known prefix (a typo in the prefix). The platform never treats an unusable credential as anonymous. Even a value with an unknown prefix lands here and not on a 404.

Solution: Check that the header reads exactly Authorization: Bearer ak_… and that the environment variable is set (echo "$SZENERA_API_KEY" | cut -c1-3 must show ak_). Command line: exit code 3. See Your first call with curl.

401 with Auth.TokenMalformed

Meaning: The prefix ak_ is right, but the rest does not match the pattern of a key: exactly 26 characters made of digits and capital letters, without I, L, O, and U. A typical cause is a key truncated while copying, or a value with unexpected characters such as spaces, quotation marks, or lowercase letters.

Solution: Copy the full value from your secret store and check the length (echo -n "$SZENERA_API_KEY" | wc -c must print 29). Command line: exit code 3. See Your first call with curl.

401 with Auth.ApiKeyUnknown, Auth.ApiKeyRevoked, or Auth.ApiKeyExpired

Meaning: Prefix and pattern are right, but the key does not exist (a typo in the value that still fits the 26-character pattern), was revoked, or has passed its date under Valid until.

Solution: Create a new key and replace the value in your secret store. A revoked key does not come back. See Create an API key.

401 with Auth.TokenExpired

Meaning: You are sending a session token (eyJ…) from the sign-in, and it expired after 15 minutes.

Solution: For machines, use a key ak_…. If you need the sign-in flows, the refresh is described under Authentication.

403 with Permission.Denied

Meaning: The credential is valid but does not carry the permission of the operation. Each operation names its permission in the reference (such as identity.device.list), and a key has only the permissions chosen when it was created. Some permissions keys never carry, such as identity.device.list (devices), fleet.playback-history.read (the daily playback history of a display), and identity.api-key.create. You reach these routes only with a session token.

Solution: In the portal under Settings › Organization › API keys, check the columns Name / permissions and Class of the key. If the permission is missing, create a key with a suitable class or add it with Adjust individual permissions. Command line: exit code 4. See Create an API key.

403 with Permission.OperatorOnly

Meaning: The route under /v1/platform/… is open only to platform operations. No key of an organization ever gets in there. A new credential does not help here, but a different route does.

Solution: Use the route of your organization (such as GET /v1/playlists instead of a route under /v1/platform). See The areas of the reference.

402 with Billing.AddonRequired

Meaning: When creating or rotating a key: the organization’s package does not include API access. Existing keys keep working, and only new ones require the enablement.

Solution: Choose a package from Premium (“API and webhooks”) or agree on the enablement of API access by contract. See Create an API key.

404 with Resource.NotFound

Meaning: The path matches no route. On the first call it is almost always one of three things: /v1 is missing (/me instead of /v1/me), there is a typo in the path, or the base URL points to the portal instead of the API.

Solution: Check address and path. Every route begins with /v1. Command line: exit code 5. See Base URL, /v1, and stability.

404 with <Resource>.NotFound (such as Scene.NotFound, Device.NotFound)

Meaning: The route is right, but the ID does not belong to your organization or no longer exists. An ID from another organization cannot be told apart from a made-up one: both give the same 404.

Solution: Take the ID from a list of your organization (GET /v1/scenes, GET /v1/playlists, …) and match the prefix to the resource (scn_ for scenes, pll_ for playlists). See What a response contains.

422 with Validation.Failed

Meaning: A parameter or a field in the body violates the contract, such as limit=500 where at most 200 applies, a missing required field, or a wrong type.

Solution: Read details.issues: each entry names the field path and the violation. Command line: exit code 7. The command line checks a body you wrote yourself before sending and reports the field path with exit code 1. See The error format.

429 with RateLimit.Exceeded

Meaning: Too many requests in one window. The routes most prone to abuse are throttled above all: sign-in, registration, and password reset. A few other routes say so in the reference. Your first call with a key does not hit them, but anyone who repeats the sign-in in a loop does.

Solution: The header Retry-After gives the seconds until the next permitted attempt, and X-RateLimit-Reset the start of the next window. Wait, then retry, and for machines use a key instead of the sign-in. Command line: exit code 8. See Throttling and rate-limit headers.

No HTTP response: connection refused, timeout, TLS error

Meaning: The call did not reach the platform. The base URL is wrong, the port is missing or wrong, the certificate does not match the name, or a proxy blocks it.

Solution: First check the address without a credential. szenera health queries the public readiness route of your environment and does not fail on the sign-in, so a wrong port does not look like a wrong key. Command line: exit code 10. Then step 1 under Your first call with curl.

Keep the trace ID

Every error response carries traceId in the body and X-Trace-Id in the header, the same value trc_…. It is the trace of exactly this call on the platform. When you ask for help, name it. Without it, a single call cannot be found again.