Public API

Diagnosing 401, 403, 422 and 429

401 means the key was not accepted at all. 403 means it was accepted but the operation is not allowed. 422 means the request was understood and the payload was wrong. 429 means you are over the rate limit and should back off rather than retry immediately.

Reviewed August 20, 2026

Steps

1. On 401, check the key exists, has not expired and is being sent in the header you think — a truncated paste is the usual cause.
2. On 403, read the code: insufficient scope, an address outside the allow-list, or a key belonging to another workspace. Reconnecting will not help; the permission has to change.
3. On 422, read the field the response names and fix the payload.
4. On 429, honour the rate-limit headers and back off. Retrying at once makes it worse.
5. Keep the requestId from the response — it is what lets support find your exact call.

How to check it worked

The same request succeeds after the fix, and the response carries a 2xx status with the object you expected.

What usually goes wrong

• Treating 403 as a bad key and reissuing it, which changes nothing.
• Retrying a 429 in a tight loop.
• Sending the key to support instead of the request id.