What are the default limits?
- Requests
- 60 per minute, per API key
- Sent messages
- 1,000 per day, per API key (drafts do not count)
- Failed authentication
- Throttled per client IP before credentials are checked
Your key’s actual limits are returned by GET /v1/me under limits.
Which headers report my usage?
| Name | Type | Description |
|---|---|---|
X-RateLimit-Limit | integer | Requests allowed in the current one-minute window. |
X-RateLimit-Remaining | integer | Requests left in the current window. |
X-RateLimit-Reset | unix timestamp | When the current window resets, in seconds since the epoch. |
Retry-After | seconds | Only on 429 responses: how long to wait before retrying. |
429 Too Many Requests
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1767225600
X-Request-Id: req_8f2c1a9d03b44e7a1c5d
{
"error": {
"code": "rate_limited",
"message": "Rate limit of 60 requests per minute exceeded.",
"request_id": "req_8f2c1a9d03b44e7a1c5d"
}
}What happens at the daily sending limit?
When a key reaches its daily send limit, POST /v1/messages returns 429 with the code daily_limit_exceeded and a Retry-After until the next day. Rejected attempts do not use up the allowance. Saving a draft (draft: true) does not count as a send.
How should I retry?
Wait for the number of seconds in Retry-After, then retry. For other transient failures such as 502 upstream_error, retry with exponential backoff and jitter, and always send an Idempotency-Key on sends so a retry can never deliver twice.
Need higher limits? Contact support with your use case.