{"record":{"id":"e33ea2230b897d2c","repo":"Budibase/budibase","slug":"usage-limit-exceeded","errorCode":"USAGE_LIMIT_EXCEEDED","errorMessage":"You have reached your Budibase AI Credits limit for this billing cycle.","messagePattern":"You have reached your Budibase AI Credits limit for this billing cycle\\.","errorType":"error_code","errorClass":"AICreditsExhaustedError","httpStatus":402,"severity":"error","filePath":"packages/pro/src/sdk/quotas/helpers/ai.ts","lineNumber":49,"sourceCode":"  const licensedQuota = await quotas.getLicensedQuota(\n    QuotaType.USAGE,\n    MonthlyQuotaName.BUDIBASE_AI_CREDITS,\n    QuotaUsageType.MONTHLY\n  )\n  // value === -1 means UNLIMITED, nothing to cap\n  if (licensedQuota.value >= 0) {\n    await setBudibaseAICredits(licensedQuota.value)\n  }\n}\n\nexport const throwIfBudibaseAICreditsExceeded = async () => {\n  const exceeded = await quotas.usageLimitIsExceeded({\n    name: MonthlyQuotaName.BUDIBASE_AI_CREDITS,\n    type: QuotaUsageType.MONTHLY,\n    usageChange: 1,\n  })\n  if (exceeded) {\n    throw new AICreditsExhaustedError()\n  }\n}\n\nexport const setBudibaseAICredits = async (count: number) => {\n  return quotas.set(\n    MonthlyQuotaName.BUDIBASE_AI_CREDITS,\n    QuotaUsageType.MONTHLY,\n    count\n  )\n}\n","sourceCodeStart":31,"sourceCodeEnd":60,"githubUrl":"https://github.com/Budibase/budibase/blob/a81a902e9a8fe55b467d106765f6638f12e35c49/packages/pro/src/sdk/quotas/helpers/ai.ts#L31-L60","documentation":"Before spending a Budibase AI credit, throwIfBudibaseAICreditsExceeded asks the quota system whether monthly BUDIBASE_AI_CREDITS usage would exceed the licensed limit. When exceeded, it throws AICreditsExhaustedError (an HTTPError carrying code USAGE_LIMIT_EXCEEDED) with this message. It is a hard monthly billing-cycle limit on AI usage, not a transient failure.","triggerScenarios":"Any AI-powered feature call (AI config usage, AI-generated content) after the tenant consumed its monthly AI credit allowance; the +1 usageChange in usageLimitIsExceeded pushes total past the licensed value.","commonSituations":"Heavy use of AI assistance features (e.g. AI formulas, AI config generation) within one billing month; small plan with a low AI credit allocation; quota reset not yet processed at month rollover; shared tenant where teammates exhausted pooled credits.","solutions":["Wait for the monthly billing cycle to reset the AI credits usage, or upgrade the plan/license for more AI credits","Check current usage via the quota usage endpoints to confirm the limit and reset date","Use a self-hosted/external LLM (e.g. the LiteLLM proxy or your own API key) instead of Budibase AI credits where supported","Catch AICreditsExhaustedError specifically (check code USAGE_LIMIT_EXCEEDED) and show a friendly upgrade prompt"],"exampleFix":"// before: generic handling loses the signal\ntry { await runAiPrompt(prompt) } catch (err) { console.log(err) }\n// after\ntry {\n  await runAiPrompt(prompt)\n} catch (err: any) {\n  if (err?.code === \"USAGE_LIMIT_EXCEEDED\") {\n    throw new Error(\"AI credits exhausted — upgrade your plan or wait for reset\")\n  }\n  throw err\n}","handlingStrategy":"try-catch","validationCode":"const exceeded = await quotas.usageLimitIsExceeded({\n  name: MonthlyQuotaName.BUDIBASE_AI_CREDITS,\n  type: QuotaUsageType.MONTHLY,\n  usageChange: 1,\n})\nif (exceeded) { /* skip AI call, show upgrade prompt */ }","typeGuard":"function isAICreditsExhausted(err: unknown): err is AICreditsExhaustedError {\n  return err instanceof AICreditsExhaustedError\n}","tryCatchPattern":"try {\n  await runAiPrompt(prompt)\n} catch (err) {\n  if (isAICreditsExhausted(err)) {\n    // show billing-cycle limit UI; no retry until reset\n  } else { throw err }\n}","preventionTips":["Pre-check AI credit headroom before batch AI operations","Monitor monthly BUDIBASE_AI_CREDITS usage via quota endpoints","Catch the USAGE_LIMIT_EXCEEDED code explicitly in AI integrations","Plan for month-rollover resets in scheduled AI jobs"],"tags":["quotas","ai","billing","usage-limit"],"backgroundTag":"quota-limit-exceeded","analyzedSha":"a81a902e9a8fe55b467d106765f6638f12e35c49","analyzedAt":"2026-08-29T01:03:10.972Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}