--- title: "Derive a recurring invoice from an existing invoice" method: POST path: "/v1/companies/{company_id}/recurring-invoices/derivations" tags: ["CompanyRecurringInvoices"] --- # Derive a recurring invoice from an existing invoice `POST /v1/companies/{company_id}/recurring-invoices/derivations` ## Request - Base URL: `https://app.beel.es/api` - URL: `https://app.beel.es/api/v1/companies/{company_id}/recurring-invoices/derivations` - Auth: HTTP bearer Creates a recurring invoice template of this company taking its lines, recipient, series, payment data and custom fields from an existing invoice, so only the recurrence has to be described. - **`from_invoice_id`:** the source invoice. It must belong to the company in the path, and one you cannot reach is reported the same way as one that does not exist. It is not modified by this call. - **Recurrence:** `name`, `day_of_month` and `start_date` are required; `end_date` and `frequency` are optional. The cadence is not taken from the source invoice — a one-off invoice has none to copy — so it is described here like any other recurrence field: every 1 (`MONTHLY`), 3 (`QUARTERLY`) or 12 (`YEARLY`) months, `MONTHLY` when omitted. It governs the step from the first invoice onwards, not where that first one lands. - **VeriFactu:** not inherited from the source invoice. Each generated invoice is registered with AEAT, or not, according to the company's regime when it is issued. - **`custom_fields`:** the template takes those of the source invoice, each with the label the field has now; a field the company has archived since is left out instead of failing the call. ## Headers - `Idempotency-Key` string ## Request body - CreateRecurringInvoiceDerivationRequest: Derives a recurring invoice template from an existing invoice: lines, recipient, series, payment data and custom fields are taken from it, so only the recurrence is described here. The source invoice is not modified. Deliberately not a variant of `CreateRecurringInvoiceRequest`: that one requires `series_id`, `invoice_type` and `lines`, which this call does not carry. Relaxing them there would let a template be created from scratch with no lines at all. - `from_invoice_id` string, uuid, required: Invoice the template is derived from. It must belong to the company in the path; an invoice you cannot reach is reported the same way as one that does not exist. - `name` string, required - `frequency` 'MONTHLY' | 'QUARTERLY' | 'YEARLY': Generation cadence: `MONTHLY` every month, `QUARTERLY` every 3 months, `YEARLY` every 12 months. Omitted, `MONTHLY` applies. It governs the step from the first invoice onwards, not where that first one lands: the first occurrence is the first `day_of_month` on or after `start_date`, found one month at a time whatever the cadence. A yearly template starting 15 February with `day_of_month` 10 first invoices on 10 March, then every 10 March after that — it does not wait a year. - `day_of_month` integer, required: Day of the month the invoices are issued. A month that does not have that day falls back to its last day: a template on `31` issues on 28 February (29 in a leap year) and on 30 April. So `31` is how you ask for the last day of the month it generates in — there is no separate flag for it, and the accepted range stays 1–31. The adjustment does not stick and the schedule does not drift: every generation is recalculated from the `day_of_month` you sent, never from the date it was adjusted to (31 Jan → 28 Feb → 31 Mar). - `start_date` string, date, required: Date the subscription started. A past date is accepted and stored as sent — useful when migrating subscriptions from another system — but it never anchors generation in the past. `next_generation` becomes the first date of the template's own calendar on or after today (today included): the grid of `day_of_month` dates anchored at `start_date`, one every `frequency`. On a quarterly or yearly template that can be months from now, not this month. Invoices are never back-dated, so the missed periods are not generated. If today's period was already invoiced in the system you are migrating from, send a `start_date` of tomorrow (or of the next period) so it is not invoiced twice. - `draft_in_advance` boolean: Whether the template prepares a draft for review before emitting. The window is fixed at 5 days and both options emit on the scheduled day. Omitted, the template is created without the review draft. Same field, same meaning and same default as when you create a template from scratch: deriving from an invoice does not give it a second semantics. - `end_date` string, date, nullable - `send_automatically` boolean - `email_configuration` RecurringEmailConfigRequest, nullable - `recipients` Email[] - `cc` Email[] - `subject` string, nullable - `message` string, nullable ## Response `201` Recurring invoice created successfully from the source invoice - object: The envelope every successful JSON response of the BeeL. API is wrapped in. There are no bare resources in v1 and none are planned: the payload always hangs off `data`. - A **single resource** is an object in `data`. - A **collection** hangs off a named key inside `data`, together with its `pagination`, also inside `data` — `data: {invoices: [...], pagination: {...}}`. - A collection carries `pagination` unless its operation declares itself a **closed catalogue**: a fixed, bounded list with nothing to page through. The declaration is explicit in the operation; a missing `pagination` is never something to infer. - `GET /v1/accounts` pages by cursor (`data: {accounts: [...], next_cursor}`). It is a documented variant of pagination, not another envelope. Putting the array straight into `data` with `pagination` as its sibling is the shape a v2 would adopt; v1 is not being flipped to it. - `success` boolean, required - `data` object, required: The payload. An object for a single resource; an object holding the named collection (and its `pagination`) for a listing. Never a bare array at this level in v1. - `id` string, uuid - `name` string - `frequency` 'MONTHLY' | 'QUARTERLY' | 'YEARLY': Billing cadence of the template: `MONTHLY` every month, `QUARTERLY` every 3 months, `YEARLY` every 12 months. The day it falls on is `day_of_month`, the same anchor for all three. Set it when you create the template; a template created without it is `MONTHLY`. The cadence governs the step from the first invoice onwards, not where that first one lands: the first occurrence is the first `day_of_month` on or after `start_date`, found one month at a time. A yearly template starting 15 February with `day_of_month` 10 first invoices on 10 March, then every 10 March after that. - `day_of_month` integer: Day of the month the invoices are issued, as it was requested: this is the anchor of the schedule, not the day the last invoice happened to land on. A month that does not have that day falls back to its last day, so `next_generation` can show a different day than this one — a template on `31` generates on 28 February (29 in a leap year) and on 30 April. The adjustment never sticks and the schedule does not drift: every generation is recalculated from this value, never from the date it was adjusted to (31 Jan → 28 Feb → 31 Mar). - `start_date` string, date - `end_date` string, date, nullable - `next_generation` string, date, nullable: Date the next invoice is generated — the one this template is actually going to honour. `null`, always present and never omitted, when there is none. There is none in two cases, and only in those two: - the template is `COMPLETED`: the date left on it is the one that ran past its end and triggered the closure, not a generation still to come; - the template is `PAUSED` and its date is strictly in the past: resuming does not go back to it — it reschedules from today onwards, so that date will never be invoiced. An `ACTIVE` template always carries its date, **including a date already in the past**: that is the occurrence about to be generated, and it is your only notice that an invoice is on its way. A `PAUSED` template whose date is still ahead — today counts as ahead — carries it too: it is exactly the date resuming would keep. The stored schedule is never rewritten by any of this. `next_generation` is what gets published, not what gets kept: resuming a long-paused template still reschedules from its own anchor, as it always did. - `draft_in_advance` boolean: Whether this template prepares a draft for review before emitting. The review window is fixed at 5 days: `true` creates the draft 5 days ahead, `false` goes straight to the emission. Either way the invoice is emitted on the scheduled `day_of_month` — what changes is only whether there is a draft to look at first. Generating manually (`POST .../generate`) a period whose scheduled date is today or earlier emits the invoice on the spot: its review window has already passed. - `status` 'ACTIVE' | 'PAUSED' | 'COMPLETED': Lifecycle state of a recurring invoice schedule. - `ACTIVE`: invoices are generated on schedule. - `PAUSED`: automatic generation is stopped and the schedule is kept; `pause` says who stopped it. It can be resumed. - `COMPLETED`: the schedule has ended for good and generates nothing more; `completion` says why. Terminal: it cannot be resumed or paused. - `is_failing` boolean: Whether this template is failing right now — from the FIRST failed unattended run, not the third. The warning email only goes out on every 3rd consecutive retryable failure, so `next_generation` not moving used to be the only clue before that; this field surfaces the same signal from the very first one. `true` when either an unattended run has failed at least once and the retry streak has not been cleared by a successful generation yet (even while `status` is still `ACTIVE`, before any email fires), or `status` is `PAUSED` with `pause.reason = GENERATION_FAILURE`. Derived on every read from data already stored — it is not a new column and nothing else changes because of it. - `pause` RecurringInvoicePause, nullable: Why this schedule is paused. Present while `status` is `PAUSED`; absent otherwise, and also absent for schedules paused before this was recorded. `PAUSED` covers three facts that are not interchangeable: someone paused it, a plan downgrade paused it, or an unattended generation failed with something waiting will not fix. A transient failure (network, timeout, tax authority downtime) does NOT pause the schedule — the next run retries it. - `reason` 'USER' | 'DOWNGRADE' | 'GENERATION_FAILURE': Who stopped the schedule. `USER` a person did, from the API or the dashboard; `DOWNGRADE` the account lost the recurring-invoices feature; `GENERATION_FAILURE` an unattended run failed with something waiting will not fix — that one carries a `blocker`. - `since` string, date-time - `blocker` string: What blocked the emission, using the same codes the emission error returns (the `blockers[]` of a 422 `EMISSION_NOT_READY`). Only for `GENERATION_FAILURE`, and it may be absent when the permanent failure was not a readiness one. Resuming is rejected while this blocker is still in effect. - `completion` RecurringInvoiceCompletion, nullable: Why this schedule ended. Present while `status` is `COMPLETED`; absent otherwise, and also absent for schedules completed before this was recorded — that cause is not known and is not invented. `COMPLETED` covers facts that are not interchangeable: the owner ended it, the calendar ran out, or the agreed number of invoices did. It stays a **single** terminal status and `status` keeps its three values: no business rule branches on the cause, and a new status value would break every exhaustive `switch`. New causes land in `reason`, so treat it as an open set. - `reason` 'USER' | 'END_DATE_REACHED' | 'MAX_INVOICES_REACHED': `USER` — someone completed it (`PUT .../status` to `COMPLETED`). `END_DATE_REACHED` — the next occurrence landed past `end_date`, so there was nothing left to generate. This includes automatic generation and the common close of generating, skipping and resuming. `MAX_INVOICES_REACHED` — the `max_invoices` cap ran out: the last agreed invoice was generated (or the cap was moved down to the number already generated). When a template exhausts its cap and its `end_date` on the very same turn this is the cause reported: the cap is the fact that just happened, the date is the calendar consequence that follows. - `at` string, date-time: Instant the schedule was closed. - `series_id` string, uuid - `series_code` string - `invoice_type` 'STANDARD' | 'SIMPLIFIED': Type of the invoices a recurring template generates: `STANDARD` for an identified recipient, `SIMPLIFIED` for a recipient that is not identified. - `customer_id` string, uuid, nullable - `recipient_fiscal_name` string, nullable - `recipient_nif` string, nullable: Spanish Tax ID of the recipient. Mutually exclusive with `recipient_alternative_id`: a recipient is identified by exactly one of the two, never both, and `null` when the other one carries the identifier (or when there is no recipient identified at all). - `recipient_alternative_id` object, nullable: Alternative identifier of the recipient (NIF-IVA, passport, etc.), same shape as the customer's own `alternative_id`. Mutually exclusive with `recipient_nif`: `null` when the recipient carries a Spanish `recipient_nif` instead, or when there is no recipient identified at all. - `type` 'NIF_IVA' | 'PASSPORT' | 'COUNTRY_ID' | 'RESIDENCE_CERTIFICATE' | 'OTHER_DOCUMENT' | 'NOT_REGISTERED' | '02' | '03' | '04' | '05' | '06' | '07', required: Identifier type. Use descriptive names: - **NIF_IVA**: EU VAT number (intra-community) — *only for an EU member state other than Spain, with that country's VAT number structure* - **PASSPORT**: Passport — *allowed for any country* - **COUNTRY_ID**: Country of residence ID — *not allowed when `country_code = ES`* - **RESIDENCE_CERTIFICATE**: Residence certificate — *not allowed when `country_code = ES`* - **OTHER_DOCUMENT**: Other supporting document — *not allowed when `country_code = ES`* - **NOT_REGISTERED**: Not registered in AEAT — *requires `country_code = ES`* **⚠️ DEPRECATED numeric codes** (will be removed in v2): 02, 03, 04, 05, 06, 07 — use the descriptive names above instead. - `number` string, required: Identifier number. For `NIF_IVA`, the full EU VAT number with its country prefix (e.g. `FR40303265045`); see the VeriFactu rules on the parent schema. - `country_code` string: ISO 3166-1 alpha-2 code of the country that issued the document. Required except for `PASSPORT` and `NOT_REGISTERED`, where omitting it means `ES`. Constrains the allowed `type` values; see the VeriFactu rules on the parent schema. - `lines` InvoiceLineTemplateResponse[] - `id` string, uuid - `order` integer - `description` string - `quantity` number - `unit` string, nullable - `unit_price` number: Unit price of the template line. In both total-declared modes (`pricing_mode` other than `UNIT_PRICE`) this value is **derived and informational** (`total / quantity`, 4 decimals): re-multiplying it does not reproduce the declared total on large quantities. - `pricing_mode` 'UNIT_PRICE' | 'TOTAL_EXCLUDING_TAX' | 'TOTAL_INCLUDING_TAX': How the line amount was entered. - `UNIT_PRICE`: classic mode — the amount is derived from `unit_price` (`quantity × unit_price × (1 − discount / 100)`). - `TOTAL_EXCLUDING_TAX`: total-declared mode — `total_excluding_tax` is the exact taxable base and `unit_price` is derived and informational (`total / quantity`, 4 decimals). - `TOTAL_INCLUDING_TAX`: tax-inclusive total-declared mode — `total_including_tax` is what the customer paid (taxable base + VAT + equivalence surcharge) and the engine works the breakdown backwards so the rounded amounts add up to the declared total exactly. In both total-declared modes re-multiplying the derived `unit_price` does NOT reproduce the declared total on large quantities (1.00 € ÷ 300 units → 0.0033 × 300 = 0.99), which is precisely why the declared total is the source of truth. - `total_excluding_tax` number: Declared line total excluding taxes. Only present on lines with `pricing_mode = TOTAL_EXCLUDING_TAX`. It never includes taxes nor subtracts IRPF withholding. - `total_including_tax` number: Declared line total including taxes (taxable base + VAT + equivalence surcharge; IRPF withholding is never subtracted). Only present on lines with `pricing_mode = TOTAL_INCLUDING_TAX`. Every invoice this template generates reproduces it exactly. - `discount_percentage` number, nullable - `tax_type` string - `vat_rate` number - `regime_key` string - `equivalence_surcharge_rate` number, nullable - `irpf_rate` number, nullable - `exemption_reason` 'EXENTA_ART_20' | 'EXENTA_ART_21' | 'EXENTA_ART_22' | 'EXENTA_ART_24' | 'EXENTA_ART_25' | 'EXENTA_ART_26' | 'EXENTA_ART_140' | 'NO_SUJETA_ART_7_9' | 'NO_SUJETA_LOCALIZACION' | 'ISP_ART_84_2_A' | 'ISP_ART_84_2_B' | 'ISP_ART_84_2_C' | 'ISP_ART_84_2_D' | 'ISP_ART_84_2_E' | 'ISP_ART_84_2_F' | 'ISP_ART_84_2_G' | 'REGIMEN_ART_129' | 'REGIMEN_ART_135' | 'REGIMEN_ART_141' | 'REGIMEN_ART_154' | 'REGIMEN_ART_163_DECIES' | 'OTRO': Tax exemption reason code per the Spanish VAT Law (Ley 37/1992, LIVA), with the VeriFactu code each one is reported as. - `EXENTA_ART_20`: exempt, art. 20 (domestic operations such as medical, educational, cultural and financial services, or housing rentals). E1. - `EXENTA_ART_21`: exempt, art. 21 (exports of goods). E2. - `EXENTA_ART_22`: exempt, art. 22 (operations treated as exports). E3. - `EXENTA_ART_24`: exempt, art. 24 (free zones, warehouses and customs regimes). E4. - `EXENTA_ART_25`: exempt, art. 25 (intra-community supplies of goods). E5. - `EXENTA_ART_26`: exempt, art. 26 (intra-community acquisitions of goods). It exempts the buyer's acquisition, not a supply the seller invoices, so an invoice line that carries it is rejected with `EXEMPTION_NOT_FOR_ISSUED_INVOICE`; a supply to another Member State is `EXENTA_ART_25`. - `NO_SUJETA_ART_7_9`: not subject under art. 7 (such as the transfer of a business as a going concern, art. 7.1º). N1. - `NO_SUJETA_LOCALIZACION`: not subject by the place-of-supply rules (intra-community or non-EU services, arts. 69 and 70). N2. - `ISP_ART_84_2_A` … `ISP_ART_84_2_F`: reverse charge (the invoice states «inversión del sujeto pasivo»), art. 84.Uno.2.º letters a) (supplier not established in Spain), b) (unwrought or semi-finished gold), c) (scrap, waste and recovery materials, plastic, paper, cardboard, glass and textile waste, and semi-finished non-ferrous metal products), d) (greenhouse gas emission allowances), e) (certain real estate supplies: in insolvency proceedings, with the exemption waived, or enforcing a security) and f) (construction or renovation works). S2. - `ISP_ART_84_2_G`: reverse charge of letter g) (silver, platinum, palladium, mobile phones, consoles, laptops and tablets). The law requires these supplies to be invoiced in a special series, so an invoice line that carries it is rejected with `REVERSE_CHARGE_CASE_NOT_SUPPORTED`. - `EXENTA_ART_140`: investment gold exemption, art. 140 bis (usually with `regime_key` `04`). E6. - `REGIMEN_ART_129` (agriculture, livestock and fishing, arts. 124 to 134 bis), `REGIMEN_ART_135` (second-hand goods, art and antiques), `REGIMEN_ART_141` (travel agencies), `REGIMEN_ART_154` (equivalence surcharge) and `REGIMEN_ART_163_DECIES` (cash basis, arts. 163 decies to 163 sexiesdecies): operations of special regimes, which VeriFactu identifies by the regime key rather than by an exemption code. An invoice line that carries one is rejected with `EXEMPTION_REGIME_NOT_SUPPORTED_IN_VERIFACTU`; declare the regime with `regime_key` instead. - `OTRO`: any other provision. Requires the text in `exemption_reason_text`. E6. - `exemption_reason_text` string, nullable: Custom exemption text. Only used when exemption_reason is OTRO. - `amount` number, nullable: What the customer will be asked to transfer on the next invoice this template generates: taxable base + VAT + equivalence surcharge − IRPF withholding + disbursements (`suplidos`). It is NOT the taxable base and NOT the total with VAT: the withholding is already subtracted. The same number the next occurrence publishes as `total_to_pay`, to the cent: both come from the template's own lines through the same line pipeline the real generation uses. It is computed on the fly and stored nowhere, so it always reflects the lines the template carries right now — and it is not sortable or filterable for that reason. `null` when the template's lines cannot be priced (no lines, or lines the engine rejects). The rest of the template is still returned. - `payment_method` string, nullable - `payment_iban` string, nullable: Full IBAN of the template's own payment method, mirrored from what was sent when it was set. `null` when the template has no payment method. - `payment_swift` string, nullable: SWIFT/BIC code of the template's own payment method. `null` when the template has no payment method, or when it has one without a SWIFT code. - `payment_term_days` integer, nullable: Payment term, in days, of the template's own payment method. `null` when the template has no payment method, or when it has one without a declared term. Each generated invoice is due on its issue date plus this term. When it is `null`, the company's default `payment_term_days` (tax configuration) applies, or 30 days if the company has none. - `notes` string, nullable - `custom_fields` InvoiceCustomField[], required: The company's custom fields saved on this template, each with the label and value it was saved with; an empty array when it carries none. Every invoice the template generates copies them. The generated invoice saves each field with the label it has at that moment; a field archived after the template was saved stays listed here, but the invoices generated from then on are created without it and the template keeps generating: it is not paused for that reason. They are informational: they are not part of the VeriFactu record sent to the AEAT and do not enter its hash. - `key` string, required: Identifier of the custom field within the company, chosen when the field is created: lowercase letters, digits and `_`, up to 64 characters. It never changes. BeeL. gives it no meaning of its own. - `label` string, required: Label of the field when the invoice was saved. - `value` string, required: Text stored on the invoice. It is the text the `custom_fields` filter of the invoice list compares. - `send_automatically` boolean - `email_configuration` RecurringEmailConfigResponse, nullable - `recipients` string[] - `cc` string[] - `subject` string, nullable - `message` string, nullable - `generated_invoices` integer - `max_invoices` integer, nullable: Total number of invoices agreed for this template, or absent when the recurrence is not capped by number. It is the TOTAL agreed, not what is left: "remaining" is `max_invoices - generated_invoices`, a derived reading with no field of its own — two counters of the same fact drift, and the day they do nobody knows which one is true. What counts against it are invoices GENERATED, not calendar turns: a skip does not spend cap because it produces no invoice, and a `generate now` does because it produces a real fiscal invoice. When the last one is generated the template is closed in the act, with `completion.reason = MAX_INVOICES_REACHED`. - `last_generated_at` string, date-time, nullable - `last_generated_scheduled_date` string, date, nullable: Calendar date of the latest period this template has already invoiced: the highest `scheduled_date` in its generation history. `null` when it has never generated an invoice. It is NOT the date of `last_generated_at`. That field is the instant the most recent invoice was created; this one is the calendar slot that invoice (or an earlier one) was issued for. They diverge on purpose: a `generate now` creates today an invoice for a future slot, and a re-anchored schedule can generate a slot out of order, so the latest invoice created is not necessarily the one with the latest slot. Skipping a period does not move it: a skip produces no invoice, so it consumes no slot. Deleting a generated invoice does not move it either, with one exception: deleting the draft of the latest generation releases that slot (the period becomes available to generate again, and `generated_invoices` goes down by one), so this date moves back to the previous generated slot, or to `null` if there is none. - `source_invoice_id` string, uuid, nullable - `created_at` string, date-time - `updated_at` string, date-time - `meta` ResponseMeta - `timestamp` string, date-time - `request_id` string ## Other responses - `400`: `VALIDATION_ERROR` — the body parses but a value is not acceptable. `details` is a flat map from the offending property's name (in the contract's `snake_case`, nested paths joined with a dot, e.g. `recipient.address.postal_code`) to a message describing what is wrong with it, one entry per property. When the rejected value is one outside an enum's vocabulary, `details` instead follows `FieldDeserializationError` (`field`, `invalid_value`, `allowed_values`). Two more codes share this status for a value that passes the contract but does not fit where it is stored: `VALUE_TOO_LONG` (a text longer than its column holds) and `VALUE_OUT_OF_RANGE` (a number outside what its column holds). Nothing was written. Other `error.code` values with this status: - `EXEMPTION_INCOMPATIBLE_WITH_REGIME` — the line's `exemption_reason` cannot be declared under its `regime_key` (e.g. E2/E3 with key `01`); change the key or the reason. - `EXEMPTION_REGIME_NOT_SUPPORTED_IN_VERIFACTU` — `REGIMEN_ART_*` reasons are special regimes, not exemptions; declare the matching `regime_key` instead of an exemption reason. - `ISP_INCOMPATIBLE_WITH_SURCHARGE` — a reverse-charge line (`ISP_*`) cannot carry an equivalence surcharge; remove the surcharge or the reverse-charge reason. - `OSS_REGIME_INCOMPATIBLE_WITH_ISP` — regime key `17` (OSS/IOSS) cannot be combined with a reverse-charge `exemption_reason`; choose one. - `401`: Missing or invalid authentication. Like every other error, `message`/`detail` is localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English when the header is missing or asks for none of those. - `403`: Your account does not own or manage this company, or does not hold the required access over it. A NIF that does not exist answers the same way. That case answers `error.code` `ACTIVE_COMPANY_NOT_ACCESSIBLE`. - `404`: The `from_invoice_id` does not exist under this company. An invoice belonging to another NIF answers the same way. - `422`: Validation error. Also: `frequency` and `end_date` can each be valid on their own and still be impossible together, when the window between `start_date` and `end_date` holds no occurrence at all — a `YEARLY` template covering a calendar year, created with the year already under way, is the everyday case. The cadence and the end date come from this request, not from the source invoice, so a derivation can ask for that window just like a template created from scratch. It is rejected with `error.code` `RECURRING_NO_OCCURRENCE_IN_WINDOW`, and its `error.details` hangs off `end_date`, the field you can move; the other lever is `frequency`. It is not the same as `RECURRING_END_DATE_BEFORE_START`, which says the *next* generation of a template that already had one falls past its end: this one says there is no first invoice, and never will be. Retrying does not help — widen `end_date` or shorten `frequency`. Other `error.code` values with this status: - `EXEMPTION_NOT_FOR_ISSUED_INVOICE` — `EXENTA_ART_26` exempts the buyer's intra-community acquisition, not a sale you invoice; use `EXENTA_ART_25` for the intra-community supply. - `EXEMPT_ZERO_RATE_REQUIRES_REASON` — a 0 % IVA or IPSI line is the exemption sentinel and needs an `exemption_reason`; add one or use a real rate. - `INVALID_IRPF` — the `irpf_rate` is not a withholding rate in force (see `IrpfPercentage`); send one of the published rates. - `INVALID_IVA_SURCHARGE_PAIR` — the equivalence surcharge does not match the line's VAT rate (21↔5.2, 10↔1.4, 5↔0.62, 4↔0.5); fix either rate. - `INVALID_SURCHARGE` — the `equivalence_surcharge_rate` is not an equivalence surcharge rate (see `EquivalenceSurchargePercentage`); send one of the published values. - `IRPF_RATE_NOT_FOR_CORPORATE_ISSUER` — the issuer is a company (corporate income tax), which can only withhold 0, 19 or 24 %; use one of those. - `IRPF_RATE_ONLY_FOR_CORPORATE_ISSUER` — the rate (e.g. 9.5 % Ceuta/Melilla) only applies to corporate issuers; an individual issuer must use a personal-income-tax rate. - `PROFORMA_NOT_RECURRING` — the source invoice is a proforma; a recurring invoice can only be created from a standard or simplified invoice. - `RECIPIENT_ID_REQUIRED` — a standard invoice needs an identified recipient: a `customer_id`, or inline data with `nif` or `alternative_id`. - `RECURRING_TYPE_NOT_SUPPORTED` — the source invoice is a corrective invoice, which cannot seed a recurrence. Derive it from a standard or simplified invoice. - `REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED` — AEAT does not accept that `exemption_reason` (or its absence) with the line's `regime_key`; the message lists the reasons it admits. - `REGIME_KEY_NOT_SUPPORTED` — BeeL. cannot declare that `regime_key` to AEAT (e.g. `06`, `14`); use another key. - `REGIME_KEY_REQUIRES_RECIPIENT_NIF` — regime key `10` (collections on behalf of third parties) requires a recipient identified with a Spanish NIF. - `REGIME_KEY_REQUIRES_STANDARD_INVOICE` — the line's `regime_key` is only accepted on a standard (F1) invoice; change the invoice type or the key. - `REGIME_KEY_REQUIRES_VAT_RATE` — the line's `regime_key` only admits one VAT rate (named in the message); use that rate or an exemption reason. - `REGIME_REQUIRES_INCOMPATIBLE_EXEMPTION` — the line's `regime_key` requires one of a set of exemption reasons (e.g. `02` exports) and the line has none or another. - `REVERSE_CHARGE_CASE_NOT_SUPPORTED` — that reverse-charge case (e.g. `ISP_ART_84_2_G`, which needs a special series) is not supported; issue it outside BeeL. or use another reason. - `SIMPLIFICADA_FORBIDS_CROSS_BORDER` — a simplified invoice cannot document a cross-border operation (art. 25 exemption or not subject by place of supply); issue a standard invoice. - `SIMPLIFICADA_FORBIDS_IRPF` — a simplified invoice cannot carry IRPF withholding; remove `irpf_rate` or issue a standard invoice. - `SIMPLIFICADA_FORBIDS_ISP` — a simplified invoice cannot carry a reverse-charge (`ISP_*`) line; issue a standard invoice. - `SIMPLIFICADA_FORBIDS_SURCHARGE` — a simplified invoice cannot carry an equivalence surcharge; send `equivalence_surcharge_rate: 0` or issue a standard invoice. - `SURCHARGE_REQUIRES_REGIME` — an equivalence surcharge was sent with a `regime_key` other than `01`/`18` (e.g. `02`, `03`, `17`); only regime `18` admits it. - `429`: Rate limit exceeded. `RATE_LIMIT_EXCEEDED` when the request rate of your credential is over its limit; `TOO_MANY_REQUESTS` when an email the operation sends is held back because too many went out to that recipient in a short time. Either way, retry after the `Retry-After` seconds. `QUOTA_EXCEEDED` is the other `429`: the operation would go over a quota of your plan for the current period (issued invoices, for instance). Retrying does not help until the quota resets or the plan changes. `error.details` carries `feature_code`, `current_usage`, `quota_limit` and `reset_date`, and `RateLimit-Reset` the seconds until the reset when it is known. - `500`: Internal server error - `default`: Any status code the operation does not list above. Every operation declares it, so a generated client always has a branch to fall into and never loses the cause of a failure it did not anticipate. This is where the transport-level answers land — `405`, `406`, `415` and `429` — together with any status a future version of the API starts returning. All of them carry the same error envelope as the codes listed explicitly, so `error.code` is what tells them apart: switching on the status code alone is not enough. See «Transport-level errors» in the API description for when each one is produced. A `402` carrying `SUBSCRIPTION_REQUIRED` lands here when the account has no active subscription. `error.details` says why and what to do: `current_status` (absent if it never had one), `required_permission` and `action`. A `503` carrying `SERVICE_UNAVAILABLE` lands here too, with a `Retry-After` header: a dependency of BeeL itself (the database, the email provider) was momentarily unavailable and nothing was done. Retry after those seconds. A `502` carrying `EXTERNAL_SERVICE_ERROR` also lands here: an outbound integration the operation depends on failed or did not answer in time. It is a transient condition — retry with the same `Idempotency-Key` where the operation accepts one. One exception to the envelope: a failure of the network edge that never reaches the application (`502`, `503`, `504`, `524`) is generated by Cloudflare and its body is not BeeL's — it may not even be JSON. Treat those as "no answer", and retry. --- [API](https://skmtc.dev/beel/apis/beel-public-api.md) · [All operations](https://skmtc.dev/beel/apis/beel-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beel/apis/beel-public-api/revisions/ffbc0ae31f79?raw)