plugin-ai-api 1.0.15 → 1.0.20

package/src/server/collections/ai-api-config.ts

@@ -1,51 +1,63 @@
-/**
- * This file is part of the NocoBase (R) project.
- * Copyright (c) 2020-2024 NocoBase Co., Ltd.
- * Authors: NocoBase Team.
- *
- * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
- * For more information, please refer to: https://www.nocobase.com/agreement.
- */
-
-import { defineCollection } from '@nocobase/database';
-
-export default defineCollection({
-  name: 'aiApiConfig',
-  autoGenId: true,
-  fields: [
-    {
-      name: 'mode',
-      type: 'string',
-      defaultValue: 'llm',
-      comment: "API mode: 'llm' = direct LLM proxy, 'agent' = full AI Employee agent with tools/RAG",
-    },
-    {
-      name: 'defaultAiEmployee',
-      type: 'string',
-      comment: 'Username of the default AI Employee for system prompt injection',
-    },
-    {
-      name: 'defaultLlmService',
-      type: 'string',
-      comment: 'Name (UID) of the default LLM service. Clients can send just modelId without service prefix.',
-    },
-    {
-      name: 'enabledLlmServices',
-      type: 'json',
-      defaultValue: [],
-      comment: 'Array of llmService names to expose. Empty = expose all enabled services',
-    },
-    {
-      name: 'rateLimitPerMinute',
-      type: 'integer',
-      defaultValue: 60,
-      comment: 'Max requests per user per minute',
-    },
-    {
-      name: 'options',
-      type: 'jsonb',
-      defaultValue: {},
-      comment: 'Reserved for future extensibility',
-    },
-  ],
-});
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { defineCollection } from '@nocobase/database';
+
+export default defineCollection({
+  name: 'aiApiConfig',
+  autoGenId: true,
+  fields: [
+    {
+      name: 'mode',
+      type: 'string',
+      defaultValue: 'llm',
+      comment: "API mode: 'llm' = direct LLM proxy, 'agent' = full AI Employee agent with tools/RAG",
+    },
+    {
+      name: 'defaultAiEmployee',
+      type: 'string',
+      comment: 'Username of the default AI Employee for system prompt injection',
+    },
+    {
+      name: 'defaultLlmService',
+      type: 'string',
+      comment: 'Name (UID) of the default LLM service. Clients can send just modelId without service prefix.',
+    },
+    {
+      name: 'enabledLlmServices',
+      type: 'json',
+      defaultValue: [],
+      comment: 'Array of llmService names to expose. Empty = expose all enabled services',
+    },
+    {
+      name: 'rateLimitPerMinute',
+      type: 'integer',
+      defaultValue: 60,
+      comment: 'Max requests per user per minute',
+    },
+    {
+      name: 'quotaEnabled',
+      type: 'boolean',
+      defaultValue: false,
+      comment: 'Enable per-user request, token, and cost quotas for direct LLM mode',
+    },
+    {
+      name: 'defaultReservationOutputTokens',
+      type: 'integer',
+      defaultValue: 4096,
+      comment: 'Output tokens reserved when a request does not specify a maximum',
+    },
+    {
+      name: 'options',
+      type: 'jsonb',
+      defaultValue: {},
+      comment: 'Reserved for future extensibility',
+    },
+  ],
+});

package/src/server/collections/ai-api-model-prices.ts

@@ -0,0 +1,25 @@
+import { defineCollection } from '@nocobase/database';
+
+export default defineCollection({
+  name: 'aiApiModelPrices',
+  autoGenId: true,
+  fields: [
+    { name: 'llmService', type: 'string', allowNull: false, index: true },
+    { name: 'provider', type: 'string', allowNull: false, index: true },
+    { name: 'model', type: 'string', allowNull: false, index: true },
+    { name: 'currency', type: 'string', allowNull: false, defaultValue: 'USD' },
+    { name: 'inputPricePerMillionTokens', type: 'decimal', precision: 20, scale: 10, allowNull: false },
+    { name: 'outputPricePerMillionTokens', type: 'decimal', precision: 20, scale: 10, allowNull: false },
+    { name: 'fixedCostPerRequest', type: 'decimal', precision: 20, scale: 10, allowNull: false, defaultValue: 0 },
+    { name: 'effectiveFrom', type: 'datetimeTz', allowNull: false, index: true },
+    { name: 'effectiveTo', type: 'datetimeTz', allowNull: true, index: true },
+    { name: 'enabled', type: 'boolean', defaultValue: true, index: true },
+    { name: 'notes', type: 'text', allowNull: true },
+  ],
+  indexes: [
+    {
+      fields: ['llmService', 'model', 'effectiveFrom'],
+      unique: true,
+    },
+  ],
+});

package/src/server/collections/ai-api-usage-records.ts

@@ -22,6 +22,9 @@ export default defineCollection({
     { name: 'endpoint', type: 'string' },
     { name: 'mode', type: 'string', allowNull: true },
     { name: 'model', type: 'string', allowNull: true, index: true },
+    { name: 'resolvedService', type: 'string', allowNull: true, index: true },
+    { name: 'resolvedProvider', type: 'string', allowNull: true, index: true },
+    { name: 'resolvedModel', type: 'string', allowNull: true, index: true },
     { name: 'status', type: 'string', index: true },
     { name: 'httpStatus', type: 'integer', allowNull: true },
     { name: 'errorCode', type: 'string', allowNull: true },
@@ -31,6 +34,12 @@ export default defineCollection({
     { name: 'totalTokens', type: 'integer', allowNull: true },
     { name: 'estimatedCost', type: 'decimal', allowNull: true, precision: 20, scale: 8 },
     { name: 'currency', type: 'string', allowNull: true },
+    { name: 'costStatus', type: 'string', allowNull: true, index: true },
+    { name: 'modelPriceId', type: 'bigInt', allowNull: true, index: true },
+    { name: 'quotaPolicyId', type: 'bigInt', allowNull: true, index: true },
+    { name: 'inputPricePerMillionTokens', type: 'decimal', allowNull: true, precision: 20, scale: 10 },
+    { name: 'outputPricePerMillionTokens', type: 'decimal', allowNull: true, precision: 20, scale: 10 },
+    { name: 'fixedCostPerRequest', type: 'decimal', allowNull: true, precision: 20, scale: 10 },
     { name: 'providerRequestId', type: 'string', allowNull: true },
     { name: 'requestMetadata', type: 'jsonb', defaultValue: {} },
     { name: 'responseMetadata', type: 'jsonb', defaultValue: {} },

package/src/server/collections/ai-api-user-quota-buckets.ts

@@ -0,0 +1,24 @@
+import { defineCollection } from '@nocobase/database';
+
+export default defineCollection({
+  name: 'aiApiUserQuotaBuckets',
+  autoGenId: true,
+  fields: [
+    { name: 'policyId', type: 'bigInt', allowNull: false, index: true },
+    { name: 'userId', type: 'bigInt', allowNull: false, index: true },
+    { name: 'periodStart', type: 'datetimeTz', allowNull: false, index: true },
+    { name: 'periodEnd', type: 'datetimeTz', allowNull: false, index: true },
+    { name: 'requestCount', type: 'bigInt', allowNull: false, defaultValue: 0 },
+    { name: 'totalTokens', type: 'bigInt', allowNull: false, defaultValue: 0 },
+    { name: 'cost', type: 'decimal', precision: 20, scale: 8, allowNull: false, defaultValue: 0 },
+    { name: 'reservedRequests', type: 'bigInt', allowNull: false, defaultValue: 0 },
+    { name: 'reservedTokens', type: 'bigInt', allowNull: false, defaultValue: 0 },
+    { name: 'reservedCost', type: 'decimal', precision: 20, scale: 8, allowNull: false, defaultValue: 0 },
+  ],
+  indexes: [
+    {
+      fields: ['policyId', 'periodStart'],
+      unique: true,
+    },
+  ],
+});

package/src/server/collections/ai-api-user-quota-policies.ts

@@ -0,0 +1,32 @@
+import { defineCollection } from '@nocobase/database';
+
+export default defineCollection({
+  name: 'aiApiUserQuotaPolicies',
+  autoGenId: true,
+  fields: [
+    { name: 'userId', type: 'bigInt', allowNull: false, index: true },
+    {
+      name: 'user',
+      type: 'belongsTo',
+      target: 'users',
+      targetKey: 'id',
+      foreignKey: 'userId',
+      constraints: false,
+    },
+    { name: 'enabled', type: 'boolean', defaultValue: true, index: true },
+    { name: 'periodType', type: 'string', allowNull: false, defaultValue: 'monthly' },
+    { name: 'timezone', type: 'string', allowNull: false, defaultValue: 'UTC' },
+    { name: 'requestLimit', type: 'bigInt', allowNull: true },
+    { name: 'totalTokenLimit', type: 'bigInt', allowNull: true },
+    { name: 'costLimit', type: 'decimal', precision: 20, scale: 8, allowNull: true },
+    { name: 'currency', type: 'string', allowNull: false, defaultValue: 'USD' },
+    { name: 'rejectUnpricedModel', type: 'boolean', defaultValue: true },
+    { name: 'missingUsageBehavior', type: 'string', allowNull: false, defaultValue: 'use_reserved' },
+  ],
+  indexes: [
+    {
+      fields: ['userId'],
+      unique: true,
+    },
+  ],
+});

package/src/server/plugin.ts

@@ -10,8 +10,10 @@
 import { Plugin } from '@nocobase/server';
 import { createAiLlmRouter } from './routes/router';
 import aiApiConfigResource from './resource/ai-api-config';
+import aiApiUsageMonitorResource from './resource/ai-api-usage-monitor';
 import { RateLimiter } from './utils/rate-limiter';
 import { invalidateRolePermissionCache } from './middleware/role-permission';
+import { validateModelPrice, validateQuotaPolicy } from './validation';
 
 // Ensure dayjs timezone + utc plugins are loaded.
 // Some Docker builds ship an older @nocobase/utils whose dayjs.js does not
@@ -37,7 +39,14 @@ export class PluginAiApiServer extends Plugin {
 
   async afterAdd() {}
 
-  async beforeLoad() {}
+  async beforeLoad() {
+    this.app.db.on('aiApiModelPrices.beforeSave', async (model) => {
+      await validateModelPrice(this.db, model);
+    });
+    this.app.db.on('aiApiUserQuotaPolicies.beforeSave', (model) => {
+      validateQuotaPolicy(model);
+    });
+  }
 
   async load() {
     // 1. Register raw Koa middleware for OpenAI-compatible endpoints
@@ -48,6 +57,7 @@ export class PluginAiApiServer extends Plugin {
 
     // 2. Register admin config resource
     this.app.resourceManager.define(aiApiConfigResource);
+    this.app.resourceManager.define(aiApiUsageMonitorResource);
 
     this.app.db.on('aiApiRolePermissions.afterSave', (model) => {
       invalidateRolePermissionCache(model.get('roleName'));
@@ -59,7 +69,17 @@ export class PluginAiApiServer extends Plugin {
     // 3. Set ACL permissions for admin config + role permissions management
     this.app.acl.registerSnippet({
       name: `pm.${this.name}.configuration`,
-      actions: ['aiApiConfig:*', 'aiApiRolePermissions:*'],
+      actions: [
+        'aiApiConfig:*',
+        'aiApiRolePermissions:*',
+        'aiApiModelPrices:*',
+        'aiApiUserQuotaPolicies:*',
+        'aiApiUserQuotaBuckets:list',
+        'aiApiUserQuotaBuckets:get',
+        'aiApiUsageRecords:list',
+        'aiApiUsageRecords:get',
+        'aiApiUsageMonitor:summary',
+      ],
     });
 
     // 4. GC the rate limiter every 5 minutes to evict stale user entries.
@@ -77,6 +97,8 @@ export class PluginAiApiServer extends Plugin {
           defaultAiEmployee: '',
           enabledLlmServices: [],
           rateLimitPerMinute: 60,
+          quotaEnabled: false,
+          defaultReservationOutputTokens: 4096,
         },
       });
     }

package/src/server/resource/ai-api-config.ts

@@ -1,74 +1,82 @@
-/**
- * This file is part of the NocoBase (R) project.
- * Copyright (c) 2020-2024 NocoBase Co., Ltd.
- * Authors: NocoBase Team.
- *
- * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
- * For more information, please refer to: https://www.nocobase.com/agreement.
- */
-
-import { ResourceOptions } from '@nocobase/resourcer';
-
-/**
- * Resource for managing AI API configuration via NocoBase admin UI.
- * Singleton config pattern (same as aiSettings in plugin-ai).
- *
- * Uses custom action name 'save' instead of 'update' because NocoBase's
- * built-in middleware requires filter/filterByTk for the standard 'update' action.
- */
-const aiApiConfigResource: ResourceOptions = {
-  name: 'aiApiConfig',
-  actions: {
-    async get(ctx, next) {
-      let config = await ctx.db.getRepository('aiApiConfig').findOne();
-      if (!config) {
-        config = await ctx.db.getRepository('aiApiConfig').create({
-          values: {
-            mode: 'llm',
-            defaultAiEmployee: '',
-            defaultLlmService: '',
-            enabledLlmServices: [],
-            rateLimitPerMinute: 60,
-            options: {},
-          },
-        });
-      }
-      ctx.body = config;
-      await next();
-    },
-
-    async save(ctx, next) {
-      const values = ctx.action.params.values || (ctx.request.body as any) || {};
-      const repo = ctx.db.getRepository('aiApiConfig');
-      let config = await repo.findOne();
-
-      if (!config) {
-        config = await repo.create({
-          values: {
-            mode: values.mode ?? 'llm',
-            defaultAiEmployee: values.defaultAiEmployee ?? '',
-            defaultLlmService: values.defaultLlmService ?? '',
-            enabledLlmServices: values.enabledLlmServices ?? [],
-            rateLimitPerMinute: values.rateLimitPerMinute ?? 60,
-            options: values.options ?? {},
-          },
-        });
-      } else {
-        const updateData: Record<string, any> = {};
-        if (values.mode !== undefined) updateData.mode = values.mode;
-        if (values.defaultAiEmployee !== undefined) updateData.defaultAiEmployee = values.defaultAiEmployee;
-        if (values.defaultLlmService !== undefined) updateData.defaultLlmService = values.defaultLlmService;
-        if (values.enabledLlmServices !== undefined) updateData.enabledLlmServices = values.enabledLlmServices;
-        if (values.rateLimitPerMinute !== undefined) updateData.rateLimitPerMinute = values.rateLimitPerMinute;
-        if (values.options !== undefined) updateData.options = values.options;
-
-        await config.update(updateData);
-      }
-
-      ctx.body = config;
-      await next();
-    },
-  },
-};
-
-export default aiApiConfigResource;
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { ResourceOptions } from '@nocobase/resourcer';
+
+/**
+ * Resource for managing AI API configuration via NocoBase admin UI.
+ * Singleton config pattern (same as aiSettings in plugin-ai).
+ *
+ * Uses custom action name 'save' instead of 'update' because NocoBase's
+ * built-in middleware requires filter/filterByTk for the standard 'update' action.
+ */
+const aiApiConfigResource: ResourceOptions = {
+  name: 'aiApiConfig',
+  actions: {
+    async get(ctx, next) {
+      let config = await ctx.db.getRepository('aiApiConfig').findOne();
+      if (!config) {
+        config = await ctx.db.getRepository('aiApiConfig').create({
+          values: {
+            mode: 'llm',
+            defaultAiEmployee: '',
+            defaultLlmService: '',
+            enabledLlmServices: [],
+            rateLimitPerMinute: 60,
+            quotaEnabled: false,
+            defaultReservationOutputTokens: 4096,
+            options: {},
+          },
+        });
+      }
+      ctx.body = config;
+      await next();
+    },
+
+    async save(ctx, next) {
+      const values = ctx.action.params.values || (ctx.request.body as any) || {};
+      const repo = ctx.db.getRepository('aiApiConfig');
+      let config = await repo.findOne();
+
+      if (!config) {
+        config = await repo.create({
+          values: {
+            mode: values.mode ?? 'llm',
+            defaultAiEmployee: values.defaultAiEmployee ?? '',
+            defaultLlmService: values.defaultLlmService ?? '',
+            enabledLlmServices: values.enabledLlmServices ?? [],
+            rateLimitPerMinute: values.rateLimitPerMinute ?? 60,
+            quotaEnabled: values.quotaEnabled ?? false,
+            defaultReservationOutputTokens: values.defaultReservationOutputTokens ?? 4096,
+            options: values.options ?? {},
+          },
+        });
+      } else {
+        const updateData: Record<string, any> = {};
+        if (values.mode !== undefined) updateData.mode = values.mode;
+        if (values.defaultAiEmployee !== undefined) updateData.defaultAiEmployee = values.defaultAiEmployee;
+        if (values.defaultLlmService !== undefined) updateData.defaultLlmService = values.defaultLlmService;
+        if (values.enabledLlmServices !== undefined) updateData.enabledLlmServices = values.enabledLlmServices;
+        if (values.rateLimitPerMinute !== undefined) updateData.rateLimitPerMinute = values.rateLimitPerMinute;
+        if (values.quotaEnabled !== undefined) updateData.quotaEnabled = values.quotaEnabled;
+        if (values.defaultReservationOutputTokens !== undefined) {
+          updateData.defaultReservationOutputTokens = values.defaultReservationOutputTokens;
+        }
+        if (values.options !== undefined) updateData.options = values.options;
+
+        await config.update(updateData);
+      }
+
+      ctx.body = config;
+      await next();
+    },
+  },
+};
+
+export default aiApiConfigResource;

package/src/server/resource/ai-api-usage-monitor.ts

@@ -0,0 +1,74 @@
+import type { Context } from '@nocobase/actions';
+import type { ResourceOptions } from '@nocobase/resourcer';
+import { Op, col, fn } from 'sequelize';
+
+interface UsageSummaryRow {
+  requestCount?: string | number;
+  inputTokens?: string | number;
+  outputTokens?: string | number;
+  totalTokens?: string | number;
+}
+
+interface CostSummaryRow {
+  currency?: string;
+  totalCost?: string | number;
+}
+
+function buildWhere(ctx: Context) {
+  const params = ctx.action.params;
+  const where: Record<string, unknown> = {};
+  const start = typeof params.start === 'string' ? new Date(params.start) : undefined;
+  const end = typeof params.end === 'string' ? new Date(params.end) : undefined;
+
+  if ((start && !Number.isNaN(start.getTime())) || (end && !Number.isNaN(end.getTime()))) {
+    const startedAt: Record<symbol, Date> = {};
+    if (start && !Number.isNaN(start.getTime())) startedAt[Op.gte] = start;
+    if (end && !Number.isNaN(end.getTime())) startedAt[Op.lte] = end;
+    where.startedAt = startedAt;
+  }
+  if (params.userId !== undefined && params.userId !== '') where.userId = params.userId;
+  if (params.resolvedService) where.resolvedService = params.resolvedService;
+  if (params.resolvedModel) where.resolvedModel = params.resolvedModel;
+  if (params.status) where.status = params.status;
+  return where;
+}
+
+const aiApiUsageMonitorResource: ResourceOptions = {
+  name: 'aiApiUsageMonitor',
+  actions: {
+    async summary(ctx, next) {
+      const model = ctx.db.getCollection('aiApiUsageRecords').model;
+      const where = buildWhere(ctx);
+      const totals = (await model.findOne({
+        attributes: [
+          [fn('COUNT', col('id')), 'requestCount'],
+          [fn('COALESCE', fn('SUM', col('inputTokens')), 0), 'inputTokens'],
+          [fn('COALESCE', fn('SUM', col('outputTokens')), 0), 'outputTokens'],
+          [fn('COALESCE', fn('SUM', col('totalTokens')), 0), 'totalTokens'],
+        ],
+        where,
+        raw: true,
+      })) as unknown as UsageSummaryRow;
+      const costs = (await model.findAll({
+        attributes: ['currency', [fn('COALESCE', fn('SUM', col('estimatedCost')), 0), 'totalCost']],
+        where: { ...where, estimatedCost: { [Op.ne]: null } },
+        group: ['currency'],
+        raw: true,
+      })) as unknown as CostSummaryRow[];
+
+      ctx.body = {
+        requestCount: Number(totals?.requestCount ?? 0),
+        inputTokens: Number(totals?.inputTokens ?? 0),
+        outputTokens: Number(totals?.outputTokens ?? 0),
+        totalTokens: Number(totals?.totalTokens ?? 0),
+        costsByCurrency: costs.map((item) => ({
+          currency: item.currency || 'USD',
+          totalCost: String(item.totalCost ?? 0),
+        })),
+      };
+      await next();
+    },
+  },
+};
+
+export default aiApiUsageMonitorResource;

package/src/server/routes/chat-completions.ts

@@ -23,6 +23,7 @@ import { createRequestAbortController, isStreamingRequested, writeResponse } fro
 import { checkEmployeeAccess } from '../middleware/role-permission';
 import { extractProviderRequestId, normalizeUsage, setAiApiUsageResult, type Usage } from '../usage';
 import type PluginAiApiServer from '../plugin';
+import { AiApiQuotaError, markLlmProviderAttempted, prepareLlmBilling } from '../billing';
 
 /**
  * POST /api/ai-llm/v1/chat/completions
@@ -121,6 +122,8 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
       return;
     }
 
+    await prepareLlmBilling(ctx, resolved);
+
     const providerRequestParameters = getProviderRequestParameters(body);
     const modelOptions: Record<string, unknown> = {
       model: modelId,
@@ -197,6 +200,7 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
     const baseModel = provider.createModel();
     applyProviderRequestParameters(baseModel, providerRequestParameters);
     const chatModel = bindRequestTools(baseModel, body.tools, body.tool_choice, providerRequestParameters);
+    markLlmProviderAttempted(ctx);
 
     if (stream) {
       // ─── Streaming mode ───
@@ -222,8 +226,15 @@ export async function handleChatCompletions(ctx: Context, plugin: PluginAiApiSer
   } catch (err) {
     ctx.log.error('AI API chat completions error:', err);
     if (!ctx.res.headersSent) {
-      ctx.status = 500;
-      ctx.body = toOpenAIError(500, getErrorMessage(err, 'Internal server error'), 'server_error');
+      const isQuotaError = err instanceof AiApiQuotaError;
+      ctx.status = isQuotaError ? 429 : 500;
+      if (isQuotaError) ctx.set('X-RateLimit-Reason', err.code);
+      ctx.body = toOpenAIError(
+        ctx.status,
+        getErrorMessage(err, 'Internal server error'),
+        isQuotaError ? 'quota_error' : 'server_error',
+        isQuotaError ? err.code : undefined,
+      );
     }
   }
 }

package/src/server/routes/completions.ts

@@ -13,6 +13,7 @@ import { resolveModelString } from '../utils/resolve-service';
 import { createRequestAbortController, isStreamingRequested, writeResponse } from '../utils/streaming';
 import { extractProviderRequestId, normalizeUsage, setAiApiUsageResult, type Usage } from '../usage';
 import type PluginAiApiServer from '../plugin';
+import { AiApiQuotaError, markLlmProviderAttempted, prepareLlmBilling } from '../billing';
 
 /**
  * POST /api/ai-llm/v1/completions
@@ -112,6 +113,8 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
       return;
     }
 
+    await prepareLlmBilling(ctx, resolved);
+
     const modelOptions: Record<string, any> = {
       model: modelId,
       llmService: service.name,
@@ -154,6 +157,7 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
 
     const completionId = generateCompletionId().replace('chatcmpl-', 'cmpl-');
     const chatModel = provider.createModel();
+    markLlmProviderAttempted(ctx);
 
     if (stream) {
       await handleStreamingTextCompletion(ctx, chatModel, langchainMessages, completionId, body.model);
@@ -163,8 +167,15 @@ export async function handleCompletions(ctx: Context, plugin: PluginAiApiServer)
   } catch (err) {
     ctx.log.error('AI API completions error:', err);
     if (!ctx.res.headersSent) {
-      ctx.status = 500;
-      ctx.body = toOpenAIError(500, getErrorMessage(err, 'Internal server error'), 'server_error');
+      const isQuotaError = err instanceof AiApiQuotaError;
+      ctx.status = isQuotaError ? 429 : 500;
+      if (isQuotaError) ctx.set('X-RateLimit-Reason', err.code);
+      ctx.body = toOpenAIError(
+        ctx.status,
+        getErrorMessage(err, 'Internal server error'),
+        isQuotaError ? 'quota_error' : 'server_error',
+        isQuotaError ? err.code : undefined,
+      );
     }
   }
 }

package/src/server/routes/router.ts

@@ -21,6 +21,7 @@ import { checkRolePermission } from '../middleware/role-permission';
 import { startUsageRecord, finishUsageRecord } from '../usage';
 import { isStreamingRequested } from '../utils/streaming';
 import type PluginAiApiServer from '../plugin';
+import { finalizeLlmBilling } from '../billing';
 
 const API_PREFIX = '/api/ai-llm/v1';
 
@@ -73,7 +74,10 @@ export function createAiLlmRouter(plugin: PluginAiApiServer) {
     ctx.set('Access-Control-Allow-Origin', '*');
     ctx.set('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
     ctx.set('Access-Control-Allow-Headers', 'Authorization, Content-Type, X-AI-Mode, X-Timezone, X-Locale');
-    ctx.set('Access-Control-Expose-Headers', 'X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After');
+    ctx.set(
+      'Access-Control-Expose-Headers',
+      'X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reason, Retry-After',
+    );
     ctx.set('Access-Control-Max-Age', '86400');
 
     // ─── OPTIONS preflight — return immediately after CORS headers ────────
@@ -259,6 +263,17 @@ export function createAiLlmRouter(plugin: PluginAiApiServer) {
         } catch (usageError) {
           ctx.log.error('AI API usage record could not be finalized:', usageError);
         }
+      } else if (ctx.state.aiApiLlmBilling) {
+        try {
+          const usageResult = ctx.state.aiApiUsageResult;
+          const providerUsage = usageResult?.source === 'provider' ? usageResult.usage : undefined;
+          const succeeded = ctx.state.aiApiStreamResult
+            ? ctx.state.aiApiStreamResult.succeeded
+            : ctx.status >= 200 && ctx.status < 400;
+          await finalizeLlmBilling(ctx, providerUsage, succeeded);
+        } catch (billingError) {
+          ctx.log.error('AI API quota reservation could not be finalized:', billingError);
+        }
       }
     }
   };