Troubleshooting

402 Payment Required — quota exceeded

You hit your plan's monthly send cap. SendBolt returns HTTP 402 Payment Required on send-path endpoints when the rolling 30-day count meets or exceeds the tier limit.

Tier limits

Check usage

Every API response includes three headers so you don't have to guess:

• X-Quota-Used: 947
• X-Quota-Cap: 1000
• X-Quota-Remaining: 53

When usage ≥ 80% you also get X-Quota-Warning: 1 and the dashboard shows a yellow banner. When usage ≥ 100% requests are rejected with 402.

Fix

Option 1 — Upgrade your plan

/dashboard/settings/billing → "Change plan". Upgrades take effect immediately; you can send the rest of the month at the new cap.

Option 2 — Wait for the next billing cycle

Caps reset on the 1st of each month UTC. If today is the 28th, you can wait 3 days. Use the time to clean your suppression list + check why you're sending more than expected.

Option 3 — Talk to us

If you have a one-off blast and don't want to upgrade, email rahul@sendbolt.io for a single-month overage credit.

Common surprise causes of hitting cap

• Stuck retry loop — your code is re-sending the same email on every page reload. Check for skipped_suppressed responses and stop retrying those.
• Bot signups — fake email addresses signing up + getting verification emails. Add reCAPTCHA / rate-limiting on /signup.
• Forgotten cron — a daily digest job re-fires for inactive users. Add a "last_engaged_at < 30d" filter.
• List churn — your bounced/unsubscribed addresses still get sent to because your code doesn't honour the suppression response. See bounces & suppressions.

Quota-aware code

// Read the headers before the body
const res = await fetch(API + "/transactional/send", {...});
const remaining = parseInt(res.headers.get("X-Quota-Remaining") || "0", 10);
if (remaining < 100) {
  // Slack alert ops; this gives you 100 sends of runway before 402
  await alertOpsRemaining(remaining);
}
if (res.status === 402) {
  // Quota exhausted. Don't retry. Surface to ops + queue for next month.
  await queueForNextMonth(payload);
  return { status: "deferred", reason: "quota_exhausted" };
}

FAQ

Does the Free tier get the same deliverability features as Scale?

Yes — DKIM rotation, ARC sealing, send-time AI, bounce classifier, warmup curve, suppression auto-management are all platform-level and identical across plans. The plans differ only on the send cap + dedicated-IP availability (Pro and Scale only).

What counts as a "send"?

Every recipient address that we attempt to deliver to. A campaign to 5,000 recipients = 5,000 sends. skipped_suppressed and skipped_high_risk do NOT count — only actual attempts.

I see X-Quota-Cap: 0. What does that mean?

Your tenant has no plan row in tenant_billing yet — we treat that as the Free tier (1,000/month). To configure a plan, visit billing settings.