What To Do When Your Quota Is Exceeded

Understanding the QUOTA_EXCEEDED Error

When you submit a job and both your monthly quota and credit balance are zero, the API returns a 403 Forbidden response with the error code QUOTA_EXCEEDED. This means you have exhausted all available enrichment capacity for the current month.

The error body includes your current quota_remaining, credits_remaining, and the reset_date so you can quickly understand your situation and choose the appropriate resolution.

# 403 response when quota is exceeded
{
  "error": "QUOTA_EXCEEDED",
  "message": "Your monthly quota and credit balance are both exhausted.",
  "quota_remaining": 0,
  "credits_remaining": 0,
  "reset_date": "2024-02-01T00:00:00Z",
  "docs": "https://trustleads.ai/guides/quota-exceeded"
}

Checking Your Remaining Quota

Before running large jobs, always check your remaining quota. Navigate to /usage in the dashboard to see your current quota balance, credit balance, and a day-by-day usage chart. The Usage page also shows when your monthly quota resets.

Via the API, call GET /v1/usage to get a real-time JSON response with quota_total, quota_used, quota_remaining, and credits_remaining. Build quota checks into automated workflows to avoid mid-batch job failures.

Options When Quota Is Exceeded

You have three immediate options when your quota is exceeded: (1) Purchase a credit pack at /billing — credits are added to your balance within seconds and jobs can be resubmitted immediately; (2) Upgrade your plan at /pricing — this increases your monthly quota limit and takes effect immediately; (3) Wait for your monthly quota to reset on the first of the next calendar month at midnight UTC.

The fastest resolution is purchasing a credit pack. Credit packs are available in four sizes (500, 2,000, 10,000, and 50,000 credits) and are charged as a one-time payment. Once purchased, credits are immediately available — resubmit your failed job and it will process normally.

• Buy a credit pack at /billing (fastest — credits available in seconds)
• Upgrade to a higher plan at /pricing (increases monthly quota immediately)
• Wait for quota reset on the 1st of next month at 00:00 UTC (free)

Preventing Future Quota Overruns

If you are regularly hitting your quota limit, it is a strong signal to upgrade your plan. Running out of quota mid-month disrupts workflows and may cause time-sensitive enrichment jobs to fail. A plan upgrade is almost always more cost-effective than repeatedly purchasing credit packs.

For teams with highly variable monthly volumes, a combination of a base plan plus a credit pack reserve works well: the plan covers predictable baseline usage and the credits cover occasional volume spikes without requiring a plan upgrade.