API reference
Errors & limits
Errors return JSON with an error string. Use the HTTP status to branch in clients. Authenticated endpoints are rate-limited per key.
Status codes
| Status | When | Example |
|---|---|---|
| 401 | Missing, bare, or invalid API key | Invalid or missing API key |
| 404 | Handle not registered | Not found |
| 400 | Invalid JSON, incomplete envelope, empty batch, or an envelope that fails sealing validation (wrong key/nonce sizes, or ciphertext that decodes to plaintext) | ciphertext decodes to plaintext — seal the message… |
| 429 | Rate limit exceeded — back off until X-RateLimit-Reset | Rate limit exceeded |
| 403 | Session routes (key management) without entitlement | apiKeys entitlement required |
Rate limits
Each API key may make 120 requests per minute (sliding window). Every authenticated response reports your quota:
text
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1789000000 # unix seconds
Retry-After: 12 # only on 429On 429, sleep until Retry-After seconds have passed and retry. Polling bots should pull no more than once every few seconds.
Shape
All documented error bodies look like:
json
{ "error": "Invalid or missing API key" }