Rate limits and quotas
Requests per second, emails per day, and the headers that tell you where you stand.
Three limits, each with its own code:
| Limit | How much | When you pass it |
|---|---|---|
| Requests | 10 a second per workspace, bursts of 20 | 429 rate_limit_exceeded |
| Emails a day | Your workspace's daily cap | 429 daily_limit_reached |
| Emails you've paid for | Your plan's emails, then your credits | 402 insufficient_balance |
Headers
| Header | When | Meaning |
|---|---|---|
x-request-id | Every response | This request's id. Quote it to support. |
ratelimit-limit | When the request counted against your rate limit | The burst size: 20. |
ratelimit-remaining | When the request counted against your rate limit | Requests you can make right now. |
ratelimit-reset | When the request counted against your rate limit | Seconds until the burst is full again. |
x-charchy-emails-remaining | Sends, cancels and GET /v1/usage | Emails left to spend: your plan's emails plus your credits. |
429, 409 idempotency_in_flight and 503 sending_unavailable carry
Retry-After, in seconds. Wait at least that long.
Check where you stand
GET /v1/usage returns all of this for your workspace. Any key may call it,
including a sending-only key:
import { CharchySend } from "@charchy/send"
const send = new CharchySend() // reads CHARCHY_SEND_KEY
const { data, error } = await send.usage.get(){
"plan": {
"key": "growth",
"emails_included": 50000,
"emails_used": 12840,
"emails_left": 37160,
"term_ends_at": "2026-12-14T09:00:00.000Z"
},
"credits": { "emails": 25000, "expires_at": "2027-02-10T00:00:00.000Z" },
"daily": { "cap": 5000, "surge_cap": 10000, "used": 612, "resets_at": "2026-11-17T08:00:00.000Z" },
"rate_limit": { "requests_per_second": 10, "burst": 20 },
"test": { "daily_cap": 1000, "used": 37 }
}planisnullwithout a plan term;creditsisnullwith no credits.daily.capis the cap in force today, whichever rule below sets it.daily.surge_capis the most you can send today while healthy (surge allowance); the same ascapwhen there is none.daily.resets_atis when your count next goes down (the day is a rolling 24 hours): atsurge_cap, when there is room for one more; under it, when the oldest counted emails leave the 24 hours.
Call it from a daily health check to get alerted before
daily_limit_reached or insufficient_balance happens.
Requests per second
10 requests a second per workspace, all keys together, bursts up to 20. A batch of 100 emails is one request.
Daily caps
A daily cap stops one mistake — a loop, a leaked key — from sending a flood.
Caps count recipients over a rolling 24 hours, not a calendar day. A
request that would pass the cap is refused whole, with Retry-After saying
when there is room.
| Emails a day | |
|---|---|
| Before your workspace is approved (your team's addresses only) | 50 |
| First 7 days after your first live email | 500 |
| Starter plan | 2,500 |
| Growth plan | 5,000 |
| Pro plan | 10,000 |
| Scale plan | 25,000 |
| Credits only, no plan | 2,500 |
| Test keys and magic addresses | 1,000 (free, counted separately) |
Surge allowance. On a busy day — a launch, a sign-up rush — a plan or
credits-only workspace can send up to twice its cap while its last 7 days
stay healthy (hard bounces under 2%, spam complaints under 0.05%, or too
little mail yet to judge), so your sign-in codes keep arriving. Not before
approval or in the first 7 days. Every email is still paid for.
daily_limit_reached comes at twice the cap, not at the cap.
Until a workspace on credits only has 30 days of live sending with no automatic pause, its cap and surge are also held to about 10% of the platform's daily volume. A plan's cap is never lowered by this. An automatic pause restarts those 30 days.
GET /v1/usage always shows the cap that applies (daily.cap) and the most a
surge can reach (daily.surge_cap).
We raise caps by hand for workspaces with a clean sending history — write to support@charchy.krd.
Queued mail is never dropped
When many emails are queued, accepted ones wait their turn: bursts slow
delivery a little but never lose mail. Emails with
expires_at go first — soonest to expire
first — so set it on sign-in codes and one-time links: they overtake your
receipts, which still keep moving.
Automatic pauses
Sending pauses for a workspace when:
- hard bounces reach 4%, or spam complaints reach 0.08%, of its last 500 recipients (once at least 100 have gone out).
Volume alone never pauses sending. When an hour jumps far above your usual, your owners and admins get an email and a notification, and for the next 24 hours the same rates are judged over your last 100 recipients (once 50 have gone out) — a leaked key mailing strangers is stopped within minutes, a sign-up rush is not.
Our delivery provider can also pause a workspace's sending on its own reputation checks.
Then:
- new live requests answer
403 sending_paused; - an
account.pausedwebhook fires and your workspace's owners and admins get an email; - test keys keep working;
- live mail already accepted is held, not failed. It goes out when
sending resumes, unless its
expires_atpasses first or it has waited 3 days past its due time — then it isexpiredand refunded (held mail).
A person resumes sending, after reviewing it with you; account.resumed
fires then. The dashboard's Overview shows your bounce and complaint
rates next to these limits.