Any API that real people share has limits, and a good client treats them as part of normal life rather than as failures. This guide explains the two limits the BoltMail API enforces, lists every error you can meet and gives you retry code you can paste into a project.

Two different limits

The per-minute rate limit belongs to each key. It protects the service from bursts. The free plan allows about 20 requests per minute per key; paid plans allow more, up to hundreds. Check GET /me for your exact figure.

The monthly quota belongs to your account and counts all requests of all your keys in a calendar month (UTC). It resets on the first of the month. When it is used up, every call returns 429 with the code quota_exceeded until the reset or until you upgrade.

Reading the headers

Every authenticated response carries the numbers you need, so you never have to guess:

  • X-RateLimit-Limit: requests allowed per minute for this key.
  • X-RateLimit-Remaining: how many are left in the current minute.
  • X-RateLimit-Reset: a Unix timestamp when the window restarts.
  • X-Quota-Limit and X-Quota-Remaining: the monthly quota, on accounts that have one.
  • Retry-After: sent with a 429, the number of seconds to wait.

A well-behaved client watches X-RateLimit-Remaining and slows down before it reaches zero.

The error format

All errors share one JSON shape, so one handler covers them:

{
  "error": {
    "code": "mailbox_limit",
    "message": "This key already holds its maximum of 5 mailboxes. Delete one first.",
    "status": 403,
    "max": 5
  }
}

Branch on code, not on the message text, because messages may be reworded. Some errors add extra fields, such as retry_after or the list of valid domains.

The error codes you will meet

  • 401 unauthorized / invalid_key: no key, a wrong key, a revoked key or an expired key. Do not retry; fix the key.
  • 403 forbidden_ip / forbidden_origin: the key has restrictions that do not match this caller. Do not retry.
  • 403 mailbox_limit: the key holds its maximum of mailboxes. Delete some, then retry.
  • 403 mailbox_suspended: that mailbox was suspended. Do not retry.
  • 404 not_found, mailbox_not_found, message_not_found: the thing does not exist, or belongs to another key.
  • 409 address_taken: the username is in use. Choose another or let the API generate one.
  • 422 invalid_username, invalid_domain, username_forbidden, invalid_field: your input was rejected. Fix the request.
  • 429 rate_limited: too many requests this minute. Wait for Retry-After and retry.
  • 429 quota_exceeded: the monthly quota is gone. Retrying will not help until the reset.
  • 429 too_many_failures: too many requests with a bad key from your address. Fix the key first.
  • 400 https_required: use https for every call.
  • 503 api_disabled, unavailable, no_domains, generation_failed: the service cannot do it right now. Retry later.
  • 500 server_error: a fault on our side. Retry once or twice, then report it.

What to retry and what not to

The rule is simple: retry what is temporary, fix what is wrong. Rate limits, 503 and 500 are temporary. Everything in the 4xx range except 429 means your request itself must change, so retrying only wastes quota. A monthly quota_exceeded is the one 429 that should stop the run instead of waiting.

Exponential backoff with jitter

When a retry is appropriate, wait longer after each failure and add a little randomness so that many clients do not all return at the same instant. Prefer the server's Retry-After when it is present.

import random, time

def call(session, method, url, max_tries=5, **kw):
    for attempt in range(max_tries):
        r = session.request(method, url, **kw)
        if r.status_code < 400:
            return r
        err = (r.json().get('error', {}) if r.headers.get('content-type', '').startswith('application/json') else {})
        retryable = r.status_code in (500, 502, 503, 504) or (r.status_code == 429 and err.get('code') == 'rate_limited')
        if not retryable or attempt == max_tries - 1:
            r.raise_for_status()
        wait = int(r.headers.get('Retry-After', 0)) or min(30, 2 ** attempt)
        time.sleep(wait + random.uniform(0, 0.5))
async function call(api, method, path, body, maxTries = 5) {
  for (let i = 0; i < maxTries; i++) {
    const r = await api(method, path, body);
    if (r.status < 400) return r;
    const err = (await r.clone().json().catch(() => ({}))).error || {};
    const retry = [500, 502, 503, 504].includes(r.status) || (r.status === 429 && err.code === 'rate_limited');
    if (!retry || i === maxTries - 1) throw new Error(err.code || r.status);
    const wait = Number(r.headers.get('Retry-After')) || Math.min(30, 2 ** i);
    await new Promise(s => setTimeout(s, (wait + Math.random() / 2) * 1000));
  }
}

Staying under the limit in the first place

  • Use long polling instead of polling loops. One /wait call replaces dozens of requests.
  • Reuse mailboxes when a test allows it, rather than creating and deleting one per assertion.
  • Cap concurrency. If your key allows 180 requests per minute, run a pool that cannot exceed that, even in the worst case.
  • Do not list when you can wait. Listing messages in a loop burns quota; waiting does not.
  • Use one key per workload so that a runaway job cannot starve everything else on the same minute.

Watching your usage

Your dashboard shows meters for requests this month, mailboxes in use and active keys. Check them after a big run, and before a release that adds tests. If you keep hitting a limit, the answer is usually a plan with more headroom, which the article on plans and scaling helps you choose.