Rate limits

Requests are limited per second and per month. When you exceed the monthly limit, credits (if any) are consumed automatically. Response headers expose current limits and remaining usage.

Response headers

X-RateLimit-Limit-Second — per-second cap
X-RateLimit-Remaining-Second — remaining this second
X-RateLimit-Limit-Month — monthly quota
X-RateLimit-Remaining-Month — remaining this month
X-API-Plan — your plan name

HTTP 429

Per-second limit:

json

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Per-second limit of 25 req/s exceeded (startup plan).",
  "upgrade_url": "https://freecustom.email/api/pricing"
}

Monthly quota exhausted (no credits):

json

{
  "success": false,
  "error": "monthly_quota_exceeded",
  "message": "Monthly quota of 500,000 requests exhausted.",
  "hint": "Purchase request credits (never expire) or upgrade your plan.",
  "credits_url": "https://freecustom.email/api/credits",
  "upgrade_url": "https://freecustom.email/api/pricing"
}

Use the Retry-After header (seconds) when present to back off.