Errors, Limits, and Versioning
Handle refusals, pagination limits, and server-version changes.
Refusal codes #
| Code | HTTP status where supported | Response |
|---|---|---|
unauthenticated | 401 | Reconnect or replace the credential |
forbidden | 403 | Check the environment and access |
not_found | 404 | Check the record in this workspace |
invalid_argument | 400 | Correct the supplied arguments |
rate_limited | 429 | Wait before retrying |
unavailable | 503 | Retry when Studio is available |
An authentication response does not disclose whether a credential was unknown, expired, or revoked. An inaccessible record in another workspace is indistinguishable from a missing record.
Rate limits #
The reviewed Worker configuration specifies 120 calls per minute per authenticated credential when its rate-limiter binding is enabled. This is an implementation configuration, not a verified production service guarantee. Confirm the deployed binding before launch.
A rate-limited response provides retryAfterSec and resetsAt; HTTP responses include Retry-After where applicable. Respect the supplied delay instead of retrying immediately.
Versions #
The major version appears in /v1/mcp. The implementation contract requires breaking versions to run beside the previous major version, with at least 90 days of deprecation notice through Deprecation and Sunset headers. Additive changes do not require a major-version increase. Responses identify the MCP version through x-34five-mcp-version.
Recovery #
Reconfirm identity after reconnecting. Do not broaden credentials to bypass a refusal. See API Keys for expiry and revocation.