Limits and errors
Handle transport errors and tool-result errors separately. Keep response headers and the full error body when diagnosing a request; never include your API key in a support report.
Your Billing page reports the plan's monthly allowances. Tool schemas declare per-request input limits, including result counts and date bounds; read the current schema instead of hardcoding a common limit for every tool.
The gateway's baseline traffic buckets allow 20 requests per second per customer with a burst of 20, plus a shared 300 requests per second bucket. These buckets are per gateway replica and per route, not a guaranteed cluster-wide customer ceiling. Additional configured key or tenant limits can be stricter.
Missing, invalid, expired or revoked credentials are rejected with HTTP 401. Check WWW-Authenticate and reconnect or replace the credential. Retrying the same invalid key will not help.
Tool availability is the intersection of the endpoint, account plan and enabled-tool settings. A tool that is unavailable may be absent from tools/list, and calling it can produce an unknown-tool error. Refresh discovery and check Dashboard → Tools. Unknown tool does not by itself mean an invalid API key.
The account authorization layer rejects an exhausted monthly allowance with HTTP 429, Retry-After (seconds) and x-deny-reason. Wait for the indicated reset or review the plan. This is separate from short-term traffic limits.
The HTTP API returns HTTP 429, Retry-After and x-ratelimit-limit/remaining/reset. MCP can return HTTP 200 with a JSON-RPC -32003 error or a tools/call result with isError: true. Inspect the response body as well as the HTTP status and rate-limit headers.
Tool failures are returned as MCP results with isError: true and an actionable code such as invalid_argument, not_found, unavailable or deadline_exceeded. Correct invalid arguments before retrying. A successful HTTP response alone does not mean the tool succeeded.
API-key tool calls pass through a transactional admission check. Exhausted key or tenant
minute limits and spend budgets return resource_exhausted, with Retry-After and X-Deny-Reason metadata. Connect exposes HTTP error metadata; MCP tool results preserve retry and denial information
in _meta["deep.navy/retryAfter"] and _meta["deep.navy/denyReason"]. Inspect these rather than treating every
failure as an unknown tool. Use Retry-After for retry timing. Edge X-RateLimit-* headers describe gateway burst limits, not tenant spend caps.
Keep the request receipt: X-Request-Id on Connect responses, or _meta["deep.navy/requestId"] on MCP results. After admission it identifies the usage event; before admission it identifies
the attempted request. An unavailable response after execution can mean completion
accounting is unresolved. Inspect usage before sending a new request.
For safe duplicate detection, send an Idempotency-Key of up to 128 printable
ASCII characters without spaces. The key is scoped to the API credential and bound to the
procedure and input. Reusing it returns already_exists; it does not execute
again or replay a stored response. Reusing the same key with changed input is rejected.
This mechanism applies to API-key tool calls; OAuth sessions do not have per-key tenant budgets.
Honor Retry-After when present. For transient network or provider failures without a retry hint, use capped exponential backoff with jitter and a limited number of attempts. Do not repeatedly retry authentication, permission or validation failures.
A timed-out write may already have succeeded. List or retrieve the resource before retrying monitor creation. Never blindly repeat a create operation and assume it was cancelled.
See MCP tool error handling and MCP authorization for the protocol conventions.