Rate limits, daily caps and other limits on a credential

The per-minute limits, the optional daily cap on changes, working hours, address allowlists, expiry and branch limits that can apply to an API key, connected app or AI teammate.

What a credential may do is its grant (Scopes reference). The limits below sit beside the grant and say how much, from where and when. The organization sets them on the credential; nothing here is decided by Nova on its own.

Per-minute limits

Going over answers:

{"error": {"code": "rate_limit_exceeded",
           "message": "Too many requests. Please try again later.",
           "details": {"limit": 600, "window_seconds": 60,
                       "retry_after_seconds": 60, "count": 601}}}

Wait retry_after_seconds, then carry on. Spread bulk work out rather than bursting.

Over MCP, every message counts once against the per-minute limits, whatever it does: tools/list, tools/call, or any other. The Nova operation a tool runs is part of that message and is not counted again. A JSON-RPC batch counts once per message in it, and a batch that would go over the limit is refused whole, before any of it runs. Going over answers HTTP 429 with the rate_limit_exceeded body above, never 401, so do not sign in again; wait and retry.

Daily cap on changes

An admin can cap how many changes an API key or an AI teammate makes in a day (1 to 100,000). The cap belongs to that credential: a connector that connects as an AI teammate is counted against its own credential, not the teammate's. Reads (GET) never count. Over MCP every message is a POST, so a tool call is judged by the operation it runs: listing tools and calling a read tool never count, and a tool that changes something counts once. Once the cap is reached every change answers 429 rate_limit_exceeded with window_seconds: 86400 until the 24-hour window that began with the first counted change runs out. The person accountable for the credential gets one notification in Nova the first time it happens that day.

Working hours (AI teammates)

An AI teammate can be given working hours. Outside them it can still read, but a change answers 403 with detail.error: agent_outside_working_hours and detail.next_window_starts_at. Over MCP the same rule holds per tool: an off-shift teammate can list tools and call read tools, and a tool that changes something returns that error as its result. See Run software as an AI teammate.

Where it may be used from

A credential can be limited to a list of addresses or ranges (203.0.113.4, 203.0.113.0/24). A call from anywhere else answers 403 with the message "This credential can only be used from an address its owner allowed." Empty means anywhere.

Branches

A credential can be limited to some of the organization's branches. It then sees and changes only work (jobs, quotes, invoices, payments, bookings, time) that belongs to those branches, exactly as a person limited to those branches would.

Expiry and replacing a key

• An API key has an expiry (30 days to 2 years, or never). An expired key answers 401.
• Replacing a key issues a new one and keeps the old one working for an overlap you choose (straight away, 1 hour, 1 day or 1 week), so you can update your software without an outage.
• Pausing or retiring an AI teammate revokes its tokens immediately.

Paid actions

Texts, emails and other actions that cost money are bounded by the organization's daily budget. When it is spent, the call answers 429 spend_deferred with details.retry_at (the next day). See Errors and how to recover.