---
title: "Rate limits"
description: "How many requests you can make, what a 429 looks like, and how the SDKs, CLI and MCP server handle it."
url: https://www.unitpost.com/docs/rate-limits
section: Docs
updated: 2026-10-13
---
# Rate limits

## Rate limits

> How many requests you can make, what a 429 looks like, and how the SDKs, CLI and MCP server handle it.

Every workspace has one request budget, shared by all of its API keys, the MCP server, the CLI and apps you sign in to with OAuth: 10 requests per second by default. If you need more, contact support; we can raise it for your workspace.

### Headers

Every response from `/api/v1` carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (when the window resets, as a Unix time). Over the limit, the API answers `429` with the code `rate_limit_exceeded` and a `Retry-After` header in seconds. Nothing ran, so the same request is safe to send again after that wait.

### Limits on single operations

Some operations have a limit of their own on top of the workspace budget, because each call costs money, reaches outside Unitpost or scans a lot of data. Their 429 has a `Retry-After` but no `RateLimit-Limit`. Wait as long as it says.

- Sends that test or reach outside Unitpost: test sends of a template, email or SMS (per workspace, and per person for a sign-in), SMS opt-in requests, SMS test numbers, webhook tests, replays and flushes.
- Domains and receiving: domain checks and diagnoses, adding domains, changing a tracking subdomain, turning receiving on.
- Searches and heavy reads, which share one limit: a text search (`q`) of the email, SMS, activity and suppression lists and of conversations; the email list's `source` and `outcome` filters, the SMS list's `type` and the activity log's `channel=email`; segment previews; and an API key's usage. The request log (`GET /logs`) has its own.
- Bulk work and rendering: contact imports and their retries, contact exports, topic opt-outs for many contacts, rendering a template.
- Brand: Brand Kit writes and imports, image uploads (to the library, the logo, the workspace image and Brand Kit graphics).
- SMS setup and purchases: brand writes, campaign checks, compliance checks, quotes and confirms (which share the dashboard's purchase limits).

### SDKs, CLI and MCP

- The SDKs retry a `429`, `5xx` errors and timeouts for reads and for writes that carry an idempotency key (sends and batches always do), so a retry never sends twice. On a `429` they wait the `Retry-After` it names, up to 20 seconds. Any other write that gets a `429` comes back to your code as an error. Most SDKs let you change or turn off retries; see each README.
- The CLI retries the same way, and also retries any request on a `429`.
- MCP tool calls that reach the API draw on the same workspace budget, one request each (the docs and design-library tools don't). A rate-limited tool call's error carries `retry_after_seconds`: wait that long before calling again.

### The dashboard and Ask Unit

The dashboard has a separate, generous limit on changes per person and per workspace, and Ask Unit on messages per minute. A tool Ask Unit runs counts like the same action in the dashboard.

## Related

- [Bounces, complaints & suppression](https://www.unitpost.com/docs/deliverability): How bad addresses are handled and where to review them.
- [Webhooks](https://www.unitpost.com/docs/webhooks): Receive signed event notifications at your own endpoint.
- [Inbound routing](https://www.unitpost.com/docs/inbound): Receive emails at your domain and get clean JSON POSTed to your webhook.