# 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.

## Which limits apply

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.

## Authentication

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 access

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.

## Account quota

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.

## Traffic rate limit

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.

## Invalid input or provider failure

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.

## Tenant limits and request receipts

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.

## Retry safely

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](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#error-handling) and [MCP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) for the protocol conventions.

---

This is the Markdown copy of https://deep.navy/docs/limits.