Annual document limit across API and MCP

30 September 2026

What changes

Interactive creation of sales documents counts toward the company’s annual document limit across the app, v1 API, MCP, assistant, imports, duplication and conversion. When enforcement is enabled and the limit is exhausted, v1 returns HTTP 402 with error.type: payment_required_error and error.code: plan_limit_exceeded. MCP returns JSON-RPC -32004 with message: plan_limit_exceeded and data.http_status: 402; it does not use the REST error body.

Sales invoices, corrective and substitute invoices, quotes, delivery notes and pro-forma invoices count when created. A conversion counts its new invoice as well as the source document that already counted. Issuing, sending or cancelling an existing document does not add or return a unit. Deleting an eligible draft returns one unit to the current annual window. Supplier invoices do not count.

The affected API operations (14 in total) and their MCP tools

These existing operations can reject interactive creation at the limit. Their URLs, request fields and tool names remain the same.

The manual recurring-invoice generation operation currently has no MCP tool counterpart.

POST /v1/invoices/bulk-create and bulk_create_invoices report quota rejections per row through failures[]. The REST batch keeps its 200/207 response; it is not part of that group of 14 with a top-level 402.

Read the error details

The v1 error exposes error.details. Handle the stable error.code; the human-facing error.message is in Spanish and may change. This example comes from the invoice response contract:

{
  "error": {
    "type": "payment_required_error",
    "code": "plan_limit_exceeded",
    "message": "Has alcanzado el límite anual de documentos de tu plan (7/7). El periodo termina el 2027-03-14; amplía el plan para seguir creando documentos ahora.",
    "param": null,
    "details": {
      "resource": "documents_year",
      "current": 7,
      "limit": 7,
      "period_end": "2027-03-14T23:59:59+01:00"
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#plan_limit_exceeded",
    "request_id": "req_01HKQS5NDOCUMENTQUOTA01"
  }
}

For MCP, these same four fields are in error.data, together with http_status, code and the Spanish hint:

{
  "jsonrpc": "2.0",
  "id": "req-42",
  "error": {
    "code": -32004,
    "message": "plan_limit_exceeded",
    "data": {
      "http_status": 402,
      "code": "plan_limit_exceeded",
      "resource": "documents_year",
      "current": 7,
      "limit": 7,
      "period_end": "2027-03-14T23:59:59+01:00",
      "hint": "Has alcanzado el límite anual de documentos de tu plan (7/7). El periodo termina el 2027-03-14; amplía el plan para seguir creando documentos ahora."
    }
  }
}

Automatic issuance continues and counts

Scheduled recurring invoices, invoices from payment, store-order and subscription-cycle integrations, integration refund corrections and subscription self-invoices continue to be issued when the document limit is exhausted. They count and can take usage above the limit. Manually requesting “generate now” for a recurring invoice is interactive and can be rejected. A manual quota rejection does not record a recurring-generation failure.

Enterprise document usage is governed by your contract; this change does not introduce an automatic document cap for that plan. Usage continues to be counted.

Anticipate the limit

Review your plan with GET /v1/account/billing and monitor the app’s document usage. The account holder receives notices when usage crosses 80 %, reaches 100 % and first exceeds the limit through automatic issuance, once per annual window and threshold. Act on the warnings before interactive creation stops.

After plan_limit_exceeded, upgrade your plan to create documents now or wait until the actual period_end has passed. Repeated immediate retries will not free document quota. Keep honouring Retry-After for the separate rate-limit errors.

Related documentation