Errors
Every error code the API returns, what causes it, and whether retrying helps.
REST API failures always use one JSON shape. Branch on error; put message in
the log a person reads.
{ "error": "not_found", "message": "No server with the slug \"missing\"."}Error codes#
- unauthorized401
- No bearer key, a malformed header, an invalid key or a revoked one. Create or replace the key; repeating the same request does not help.
- invalid_request400 or 409
- A query/body value is invalid, or the requested change conflicts with the resource's state. The message names the field or conflict.
- not_found404
- The resource does not exist in the account scoped by this key. Check the slug or ID rather than retrying blindly.
- rate_limited429
- This API key spent its fixed minute. Wait `Retry-After`, then repeat the request unchanged.
- method_not_allowed405
- The endpoint does not publish this verb. Read the `Allow` response header.
- server_error500
- An unexpected Omniio failure. Retry with backoff; report a persistent failure with its UTC time.
Retry decisions#
| Condition | Retry? | Change first |
|---|---|---|
| 400 invalid parameter | No | Correct the named query or body field. |
| 401 invalid key | No | Replace or un-revoke the credential. |
| 404 missing resource | No | Refresh the library or use the correct account/slug. |
| 409 credentialed server PATCH | No | Connect or disconnect it in the app. |
| 429 rate limit | Yes | Wait the exact Retry-After seconds. |
| 500 server error | Yes | Use bounded exponential backoff. |
All responses, including failures, carry CORS headers. Authenticated metered
failures also carry the current X-RateLimit-* values.
Parameter rules#
Unknown query parameters are ignored, but every documented value is validated.
Integers must be base-10 whole numbers inside the endpoint's range; out-of-range
values are refused rather than clamped. Activity cursors must be the exact ISO
8601 shape returned as nextCursor, and boolean filters use the literal strings
true or false.
PATCH /servers/{slug} requires parseable JSON and a boolean enabled field.
It returns 409 for a real server whose authentication state cannot be changed by
that endpoint, and 404 only when no such server exists.
MCP failures#
The MCP endpoint returns tool errors as MCP tool results rather than REST error codes. The message states the actionable condition: burst wait, monthly reset, disabled or unknown tool, denied policy, pending approval, connection failure, invalid arguments or the upstream's own refusal.
A refused run_tool is written to Activity when it reaches the run gate. Search
and description failures are not Activity rows, though their attempted calls may
still count toward monthly usage if they passed burst protection.
Next: Data handling.