An API request is rejected with 401, 403, 409 or 429

What you see

A request to /api/v1 returns a JSON error and a status code:

{ "error": { "code": "forbidden", "message": "API key lacks capability 'hosting_view'" } }

Cause

401 unauthorized: “missing or invalid API key”

The Authorization header is missing, or does not read Bearer hyp_…. A token without the hyp_ prefix is ignored.
The key was revoked, has expired, or was mistyped. A key is shown only once when it is created.
The panel could not look the key up. Retry once, then check that hyperion-agent is running on the master.

Check: API keys in the sidebar lists each key by prefix with its Expires date, and revoked keys are marked revoked.

403 forbidden

Message	Cause
API key lacks capability ‘<name>’	The key was created without that capability. Create a new key that has it. A key can never hold more than its creator.
source IP not allowed for this API key	The key has Allowed addresses and the request comes from another address. Behind a proxy, only the panel’s own nginx may set `X-Real-IP`.
job polling requires a cluster-wide (scope_all) API key	`GET /api/v1/jobs/<id>` needs a cluster-wide key.
cluster certificate renewal requires a cluster-wide (scope_all) API key	The same for `POST /api/v1/certs/renew-all`.

Changing custom_nginx_snippet through PATCH …/vhost also needs the hosting_edit_nginx_raw capability.

400 validation

The body is malformed or a field is invalid, and the message says which. Frequent causes:

php_version or version written as 8.3. The API uses v8_3.
PATCH …/limits sent with only some fields. It replaces the whole object, so send all the required ones.
system_user may only be set by a cluster-wide key.
version is required for wp/core-update, archive_path is required for restore.

404 not_found

“no such hosting” or “no such job”. Use the hosting id or its exact domain.

409 conflict

“a hosting for example.com already exists” on create. The domain is used on this node or another one. www. is removed from the domain before the check.

429 rate_limited

“rate limit exceeded for this API key”. The key has Requests per minute set and you went over it. The answer carries Retry-After: 60. Slow the script or create a key with a higher limit; 0 means unlimited.

502 upstream_error

The agent or the node that owns the hosting did not answer, or answered with an error. The message is the agent’s. Check the node as in A node shows as unreachable.

Fix

Fix the key, the address or the request as above. See the HTTP API reference for every endpoint and body.

Check that it is fixed

hyp is the shell function defined in the HTTP API reference; it keeps the key off the command line.

hyp https://panel.example.com/api/v1/me

The answer lists the key’s id, label, caps and scope_all.