Limits

Design v3 clients around bounded tool calls, connection lifetime, payload size and seller latency.

v3 shares the platform’s transport protections and adds a few bounds of its own. Build for them from the start; they are what keep one slow seller or one large report from stalling everyone else.

MCP bounds

Bound	Limit
One MCP connection	Up to 30 minutes. Deploys may end it sooner.
MCP session	Dropped after 60 minutes idle, or when the server restarts; re-initialize on 404 Session not found.
One tool call	Up to 30 minutes, then SERVICE_UNAVAILABLE: the call may still have happened, so read state before retrying.
Structured response size	Responses over 200 KB are truncated as a safety net. Page with limit and cursor.
Proposal executions	One running request_proposals execution per buyer account.
Each seller in an execution	Bounded to 30 seconds. A seller that does not answer in time is reported as failed or pending.
Delivery ranges	get_delivery accepts up to 90 days, or { "lifetime": true }.
Idempotency keys	16 to 255 characters from A–Z a–z 0–9 _ . : -. Replays are honored for 24 hours.
Confirmations	A pending_confirmation expires after 15 minutes.

Rate limits

Semicola counts requests in fixed windows:

Scope	Window	Limit
Each API key or OAuth token (REST and MCP)	1 minute	100 requests
Each client IP, for signed-in app sessions and anonymous calls	1 minute	100 requests
Sign-in and other /auth/* routes, per IP	15 minutes	40 requests
Signup, per IP	1 hour	20 requests
Password reset (request, verify and reset), per IP	1 hour	12 requests
OAuth client registration (/auth/register), per IP	1 hour	20 requests
OAuth token and revocation (/auth/token, /auth/revoke), per IP	15 minutes	300 requests
Credentials that don’t verify, per IP	1 minute	30 requests

A bearer credential counts against itself, not the IP, once it verifies, so many agents behind one host (Claude, ChatGPT) don’t share one budget. A credential that doesn’t verify (unknown, revoked or malformed) counts against the IP instead, and after 30 of those in a minute the IP’s API keys are refused (429) until the window ends, except keys that verified in the last minute; an invalid access token keeps getting the 401 challenge. A valid key’s parallel requests are limited only by its own 100 per minute, and a revoked key is refused on its next request. An expired access token of ours counts against the IP but not as a failure: refresh it. CORS preflight (OPTIONS) requests count against the IP too. An IPv6 client is counted per /64 network; an IPv4 address written in IPv6 form counts as that IPv4 address. /health, /.well-known/* and public /assets/* aren’t counted. The realtime streams aren’t counted either; each user may hold 10 open at a time.

Each account may hold 100 active API keys and register 50 browser origins; revoke or remove one to add another.

Every counted response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). Over the limit you get:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 42

{ "data": null, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Try again later." } }

Read RateLimit-Remaining on every response and slow down before it reaches zero.

Backoff

1. Honor Retry-After. It says when to retry.
2. Add jitter, about ±25%, so clients don’t all retry at the same moment.
3. Cap retries at 3 to 5, then show the error to the person.
4. Be careful with writes. Retry a create only with the same Idempotency-Key (REST) or idempotencyKey (MCP), so a retry can’t create a duplicate.

Polling cadence

What you’re waiting on	Poll at most
GET /api/v2/buyer/campaigns/{id}/media-buy-status	every 30 seconds
A campaign after launch	every 15 to 30 seconds; prefer webhooks
A proposal request (get, kind: "proposal")	every 5 to 10 seconds while sellers answer

If you poll faster and see RATE_LIMITED, slow down.

Designing around them

• Do not hold a call open. request_proposals returns straight away with running; follow progress with get or in the Proposals widget instead of waiting on one call.
• Keep pages small. Use cursors and bounded limit values, and preserve partial results between pages.
• Expect seller latency. Sellers and their inventory systems often dominate response time even when Semicola itself is healthy.
• Reuse keys only for true retries. An idempotency key identifies one logical attempt.

Local development builds shorten some bounds so demos stay snappy, for example a two-minute tool call and a 20-second seller window.