# Errors (https://docs.getbeel.com/en/api/errors)

The error shape, HTTP statuses and every code the API can return, with what to do.

Every error has the same shape:

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "message": "Unknown parameter 'starting_after'. Allowed: limit, cursor, status, date_from, date_to, payment_status, overdue, search.",
    "param": "starting_after"
  }
}
```

- `type` is the category.
- `code` is stable: use it in your code to decide what to do.
- `message` is for people and may change.
- `param`, when present, names the field, parameter or header to fix.

Every response, successful or not, has an `X-Request-Id` header (`req_…`). Quote it when you contact support.

## Types and HTTP statuses [#types-and-http-statuses]

| `type`                  | Status                       | When                                                        |
| ----------------------- | ---------------------------- | ----------------------------------------------------------- |
| `authentication_error`  | 401                          | Key or token missing, wrong, revoked, expired or suspended  |
| `permission_error`      | 402, 403                     | A scope, a plan or the right mode (test or live) is missing |
| `invalid_request_error` | 400, 404, 409, 413, 415, 422 | The request is invalid, or invalid in the current state     |
| `not_found_error`       | 404                          | The resource does not exist or is not in your team          |
| `rate_limit_error`      | 429                          | Too many requests, see [Rate limits](/en/api/rate-limits)   |
| `api_error`             | 500, 502, 503, 504           | Our error or an external service's: try again later         |

General rule: fix a `4xx` before repeating the request (except the concurrency `409`s and `429`, listed below); retry `5xx` and network errors with backoff and the same [idempotency key](/en/api/idempotency).

## Codes [#codes]

The list comes from the API code (every `ApiError` an endpoint or an MCP tool can return).

### Authentication and permissions [#authentication-and-permissions]

| `code`                        | Status | Meaning                                                                                                                                                                                                     | What to do                                                                                                       |
| ----------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `missing_api_key`             | 401    | The `Authorization` header is missing                                                                                                                                                                       | Send `Authorization: Bearer gb_…`                                                                                |
| `invalid_api_key`             | 401    | Unknown or malformed key                                                                                                                                                                                    | Check the key in Settings → API keys & MCP                                                                       |
| `api_key_revoked`             | 401    | Key revoked, or its creator left the team                                                                                                                                                                   | Create a new key                                                                                                 |
| `api_key_expired`             | 401    | Key expired                                                                                                                                                                                                 | Create a new key                                                                                                 |
| `api_key_suspended`           | 401    | The key's creator can no longer manage API keys                                                                                                                                                             | Have a member with that permission create the key                                                                |
| `invalid_token`               | 401    | OAuth token (`gb_oat_…`) expired, revoked or invalid                                                                                                                                                        | Refresh it; if that fails, connect the app again                                                                 |
| `insufficient_scope`          | 403    | The required scope (named in the message) is missing                                                                                                                                                        | Create a key with that scope (keys cannot be edited) or reconnect the app                                        |
| `insufficient_permissions`    | 403    | The key's creator cannot add client companies                                                                                                                                                               | Use a key of a member with that permission                                                                       |
| `livemode_required`           | 403    | The operation changes real data and needs a live key                                                                                                                                                        | Use a `gb_live_…` key                                                                                            |
| `test_mode_required`          | 403    | The receiving sandbox only takes test keys                                                                                                                                                                  | Use a `gb_test_…` key                                                                                            |
| `company_not_eligible`        | 403    | Issuing invoices needs an Italian company profile                                                                                                                                                           | Complete Settings → Company                                                                                      |
| `invite_not_allowed`          | 403    | The key's creator cannot invite a commercialista                                                                                                                                                            | Use a key of a member with that permission                                                                       |
| `remove_not_allowed`          | 403    | The key's creator cannot remove that commercialista                                                                                                                                                         | As above                                                                                                         |
| `sdi_addon_required`          | 402    | Live invoices (or Stripe sync) need the SDI plan                                                                                                                                                            | Turn it on in Settings → Usage & billing (for a client company, on the parent account); in test, use the sandbox |
| `sdi_quota_exhausted`         | 402    | This month's SDI quota is used up                                                                                                                                                                           | Upgrade the SDI plan, or wait for next month                                                                     |
| `insufficient_balance`        | 402    | The prepaid balance does not cover the action (pay as you go); the answer is `application/problem+json` with `balance_cents`, `required_cents` and `topup_url` (only `required_cents` for a client company) | Add credits from `topup_url` (Settings → Billing & usage) or turn on auto top-up                                 |
| `no_card`                     | 409    | No card is saved yet, so there is no card to change (`POST /billing/payment-method`); `application/problem+json` like `insufficient_balance`                                                                | Add a card with a top-up or in Settings → Billing & usage                                                        |
| `not_pay_as_you_go`           | 409    | Usage, top-ups and card links are for pay-as-you-go accounts                                                                                                                                                | The account (signed up before 13 November 2026) keeps its plan: see `GET /usage`                                 |
| `billing_permission_required` | 403    | The key's creator cannot manage billing                                                                                                                                                                     | Use a key of a member with the billing permission                                                                |
| `billed_to_parent`            | 403    | A client company pays from its gestore's balance (its own key reads neither the balance nor the usage)                                                                                                      | Add credits on the parent account                                                                                |
| `subscription_required`       | 402    | The paid product is needed (invoice processing, reconciliation)                                                                                                                                             | Pick a plan in Settings → Usage & billing                                                                        |
| `limit_reached`               | 402    | The plan's number of mailboxes is reached                                                                                                                                                                   | Disconnect a mailbox or change plan                                                                              |

### Request [#request]

| `code`                       | Status   | Meaning                                                                                                        | What to do                                                                  |
| ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `parameter_unknown`          | 400      | Unknown query parameter (the message lists the allowed ones) or, on `PATCH /invoices/{id}`, unknown body field | Remove it or fix its name (for example `cursor`, not `starting_after`)      |
| `rate_limit_exceeded`        | 429      | Too many requests for the key                                                                                  | Wait `Retry-After` seconds, then retry ([Rate limits](/en/api/rate-limits)) |
| `parameter_invalid`          | 400      | A parameter, field or header is invalid (see `param`)                                                          | Fix the value                                                               |
| `parameter_missing`          | 400      | A required parameter is missing                                                                                | Add it                                                                      |
| `invalid_json`               | 400      | The body is not valid JSON                                                                                     | Send valid JSON with `Content-Type: application/json`                       |
| `invalid_multipart`          | 400      | The multipart body cannot be read                                                                              | Send `multipart/form-data` with a `file` field                              |
| `file_url_unusable`          | 400, 413 | `file_url` is not a public https link answering 200 without redirects, or the file is over 50 MB               | Use a direct public link, or upload the file                                |
| `payload_too_large`          | 413      | JSON body over 1 MB; XML over 5 MB (the SDI limit for one file); bank statement over 50 MB; receipt over 10 MB | Make the file smaller                                                       |
| `file_invalid`               | 413      | A filing receipt is over 10 MB                                                                                 | Upload a smaller file                                                       |
| `unsupported_media_type`     | 415      | Unsupported `Content-Type`                                                                                     | Use the one named in the message                                            |
| `unsupported_file_type`      | 415      | Unsupported bank statement type (for example a spreadsheet)                                                    | Upload PDF, CSV, TXT, CBI, CAMT.053 or MT940                                |
| `resource_missing`           | 404      | No resource with that id in your team                                                                          | Check the id (and `Getbeel-Company` or `company_id`)                        |
| `company_not_found`          | 404      | The client company does not exist or is no longer available                                                    | Use an id from `GET /companies`                                             |
| `numbering_series_not_found` | 404      | The numbering series does not exist                                                                            | Use an id from `GET /numbering-series`                                      |
| `received_invoice_not_found` | 400      | The received invoice given for the fixed asset is not in this company                                          | Use an id from `GET /received-invoices`                                     |

### Idempotency and concurrency [#idempotency-and-concurrency]

| `code`                     | Status | Meaning                                                    | What to do                                                  |
| -------------------------- | ------ | ---------------------------------------------------------- | ----------------------------------------------------------- |
| `idempotency_key_in_use`   | 409    | A request with the same `Idempotency-Key` is still running | Retry in a few seconds with the same key                    |
| `idempotency_key_reused`   | 422    | The key was already used for a different request           | Use a new key for a new request                             |
| `invoice_send_in_progress` | 409    | A send of this invoice is already running                  | Do not repeat it: read the status with `GET /invoices/{id}` |
| `sync_in_progress`         | 409    | A sync of this bank connection is running or just ran      | Retry in a minute                                           |
| `filing_conflict`          | 409    | The filing is being prepared right now                     | Retry in a few seconds                                      |
| `reconciliation_conflict`  | 409    | The match changed meanwhile                                | Read the reconciliation again and retry                     |

### Issued invoices and sending to SDI [#issued-invoices-and-sending-to-sdi]

| `code`                           | Status | Meaning                                                                                    | What to do                                                                                                                                                                                                                       |
| -------------------------------- | ------ | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invoice_not_draft`              | 409    | Only a draft can be sent or edited: this one was already sent                              | Do not resend it: read the status and the outcome in `sdi` ([SDI lifecycle](/en/api/sdi-lifecycle)). On `PATCH`: a rejected invoice is reopened first (`POST /invoices/{id}/reopen`), a sent one is corrected with a credit note |
| `invoice_not_sendable`           | 409    | A proforma is not sent to SDI                                                              | Create a real invoice                                                                                                                                                                                                            |
| `invoice_not_rejected`           | 409    | Only an invoice rejected by SDI can be reopened, and not while an automatic fix is running | Check the status: a `delivered`, `not_delivered` or `00404` invoice is issued and is never reopened. A `draft` is edited as it is (`PATCH`); a delivered one is corrected with a credit note                                     |
| `invoice_invalid`                | 422    | The invoice fails the local checks (FatturaPA XML or credit note rules)                    | Fix what the message says                                                                                                                                                                                                        |
| `invoice_number_taken`           | 409    | An invoice with this number already exists                                                 | Leave the number out (getbeel assigns the next one) or pick a free one                                                                                                                                                           |
| `invoice_number_out_of_sequence` | 422    | The number would jump ahead in the numbering                                               | Use the next number or one that fills a gap                                                                                                                                                                                      |
| `company_profile_incomplete`     | 422    | The company profile lacks what is needed to issue (name, partita IVA or codice fiscale…)   | Complete Settings → Company                                                                                                                                                                                                      |
| `credit_exceeds_invoice`         | 422    | The credit note exceeds what is left to credit on the invoice                              | Reduce the lines                                                                                                                                                                                                                 |
| `invoice_not_issued`             | 409    | An invoice SDI accepted is needed (for a credit note, a payment, a link)                   | Wait for the outcome, or pick another invoice                                                                                                                                                                                    |
| `invoice_not_creditable`         | 409    | This invoice cannot be credited (proforma or credit note)                                  | Pick the original invoice                                                                                                                                                                                                        |
| `sdi_send_failed`                | 502    | The send did not start: the invoice stays a draft                                          | Try again later                                                                                                                                                                                                                  |
| `internal_error`                 | 500    | Internal error (for example the invoice could not be created)                              | Retry; if it persists, contact support with `X-Request-Id`                                                                                                                                                                       |

An **SDI rejection** is not an API error: the send succeeds, then SDI answers. See below.

### Quotes, numbering series and collection [#quotes-numbering-series-and-collection]

| `code`                     | Status | Meaning                                                        | What to do                                  |
| -------------------------- | ------ | -------------------------------------------------------------- | ------------------------------------------- |
| `quote_not_editable`       | 409    | The quote can no longer be edited                              | Create a new one                            |
| `quote_converted`          | 409    | The quote already became an invoice                            | Use the invoice created                     |
| `quote_invalid`            | 422    | The quote is not valid                                         | Fix what the message says                   |
| `numbering_series_exists`  | 409    | A series with this prefix or suffix already exists             | Pick another one                            |
| `numbering_series_in_use`  | 409    | The series has invoices and cannot be changed or deleted       | Create a new one                            |
| `numbering_series_invalid` | 422    | The series is not valid                                        | Fix what the message says                   |
| `natura_required`          | 422    | An item at 0% VAT has no `natura` (SdI would refuse it: 00400) | Give the `natura` (N1–N7) or a rate         |
| `customer_email_missing`   | 422    | The customer has no email address                              | Pass `to` or add the email to the customer  |
| `email_failed`             | 502    | The email was not sent                                         | Try again later                             |
| `invoice_already_paid`     | 409    | The invoice is already paid                                    | Nothing to do                               |
| `amount_exceeds_balance`   | 422    | The payment exceeds the amount due                             | Reduce the amount                           |
| `invoice_pdf_missing`      | 409    | The invoice PDF is not ready yet                               | Try again shortly                           |
| `invoice_not_copyable`     | 422    | The invoice cannot be repeated (for example a credit note)     | Use an ordinary invoice                     |
| `recurring_invoice_exists` | 409    | This invoice already repeats                                   | Change the existing schedule                |
| `stripe_not_connected`     | 409    | No active Stripe connection                                    | Connect Stripe (`POST /connections/stripe`) |
| `stripe_mode_mismatch`     | 409    | The Stripe connection is in the other mode (test or live)      | Use a key of the same mode                  |
| `stripe_error`             | 502    | Stripe error                                                   | Try again later                             |

### Banks, connections and documents [#banks-connections-and-documents]

| `code`                               | Status   | Meaning                                                                         | What to do                                          |
| ------------------------------------ | -------- | ------------------------------------------------------------------------------- | --------------------------------------------------- |
| `bank_connection_inactive`           | 409      | The connection is not active                                                    | Finish the bank login or reconnect                  |
| `bank_connection_requires_reconnect` | 409      | The consent expired or was revoked                                              | Reconnect the bank                                  |
| `bank_connection_conflict`           | 409      | The connection changed meanwhile                                                | Read it again and retry                             |
| `bank_connection_limit`              | 409      | The maximum number of connected banks is reached                                | Disconnect one                                      |
| `bank_credentials_invalid`           | 422      | The Enable Banking app credentials are invalid                                  | Check the credentials                               |
| `redirect_url_not_allowed`           | 422      | The return URL is not allowed                                                   | Use an allowed https URL                            |
| `bank_daily_limit`                   | 429      | The bank allows about four unattended updates a day, used up                    | getbeel retries by itself later                     |
| `bank_error`, `bank_sync_failed`     | 502      | Bank or Enable Banking error                                                    | getbeel retries; try again later                    |
| `bank_unavailable`                   | 503      | Banking service unavailable                                                     | Try again later                                     |
| `connection_not_scannable`           | 409      | The mailbox cannot be scanned now                                               | Read the message (connection expired, scan running) |
| `reconnect_required`                 | 409      | The mailbox authorization expired or was revoked; no scan was created           | Reconnect the mailbox in the app, then scan again   |
| `imap_connect_failed`                | 422      | IMAP connection failed                                                          | Check email, password, server and port (993)        |
| `rate_limited`                       | 429      | Too many IMAP connection attempts                                               | Try again later                                     |
| `unavailable`                        | 503      | Feature not available on this deployment, or an external service is unreachable | Try again later                                     |
| `internal`                           | 500      | Internal error while connecting IMAP                                            | Retry; contact support with `X-Request-Id`          |
| `invoice_not_reviewable`             | 409      | The collected document is not waiting for review                                | Nothing to do                                       |
| `workflow_unavailable`               | 503      | Background processing is not available                                          | Try again later                                     |
| `storage_error`                      | 500, 503 | The file was not stored                                                         | Retry                                               |
| `file_url_unreachable`               | 502, 504 | `file_url` could not be downloaded                                              | Retry or upload the file                            |
| `file_empty`                         | 400      | The file sent is empty                                                          | Send the file again                                 |
| `credits_exhausted`                  | 402      | No invoice credits left for the upload                                          | Buy a pack or change plan in Usage & billing        |
| `processing_unavailable`             | 503      | The upload could not start reading the file                                     | Retry                                               |
| `default_category`                   | 409      | A default category cannot be deleted                                            | Delete another category, or rename this one         |
| `unknown_category`                   | 422      | Not a category of this team                                                     | Use a slug from `GET /categories`                   |
| `folder_exists`                      | 409      | A Drive folder with that name exists there                                      | Pick another name                                   |
| `folder_too_large`                   | 503      | The Drive folder has too many files to delete at once                           | Try again: each call deletes more                   |
| `statement_has_sent_autofatture`     | 409      | The statement holds autofatture at SDI: a fiscal record                         | Keep it; it cannot be deleted                       |

### SDI receiving and client companies [#sdi-receiving-and-client-companies]

| `code`                        | Status | Meaning                                                         | What to do                                  |
| ----------------------------- | ------ | --------------------------------------------------------------- | ------------------------------------------- |
| `company_not_ready`           | 422    | The company does not have what it needs to receive from SDI yet | Complete the steps in `GET /sdi-receiving`  |
| `fiscal_id_taken`             | 409    | The partita IVA is already set up for receiving elsewhere       | Contact support                             |
| `invoice_unreadable`          | 422    | The test XML cannot be read                                     | Fix the XML (for example the document date) |
| `sdi_provider_unavailable`    | 502    | The receiving channel does not answer                           | Try again later                             |
| `company_nesting_not_allowed` | 409    | A client company cannot have client companies                   | Use the parent account's key                |
| `already_member`              | 409    | The person is already in the team                               | Nothing to do                               |
| `already_invited`             | 409    | There is already an invitation for another role                 | Revoke it in the app                        |

### Filings, VAT, withholdings, fixed assets, POS–RT [#filings-vat-withholdings-fixed-assets-posrt]

| `code`                       | Status   | Meaning                                                         | What to do                                 |
| ---------------------------- | -------- | --------------------------------------------------------------- | ------------------------------------------ |
| `taxes_not_available`        | 400      | Taxes are available for Italian companies only                  | Set the country to Italy in the profile    |
| `vat_not_applicable`         | 400      | A regime without VAT (forfettario or minimi)                    | No VAT registers or settlements to prepare |
| `settings_missing`           | 400      | The VAT period (monthly or quarterly) is not set                | Set it in Taxes → Settings                 |
| `settlements_missing`        | 400      | The quarter's saved settlements for the LIPE are missing        | Save the settlements named first           |
| `period_not_closed`          | 400      | The period is not over                                          | Prepare the filing after the period ends   |
| `period_not_started`         | 400      | The month has not started                                       | Pick a period that has started             |
| `nothing_due`                | 422      | Nothing is due in the period                                    | No F24 to prepare                          |
| `filing_completed`           | 409      | The filing is already paid or filed and no longer changes       | Nothing to do                              |
| `file_missing`               | 400      | The receipt was not uploaded                                    | Upload it again                            |
| `file_invalid`               | 500      | The generated LIPE file fails the official XSD check            | Contact support with `X-Request-Id`        |
| `too_many_documents`         | 400, 422 | Too many documents in the period to compute it here             | Pick a shorter period or contact support   |
| `withholding_exists`         | 409      | The received invoice already has a withholding                  | Update that one                            |
| `withholding_remitted`       | 409      | The withholding was already paid with an F24                    | It can no longer change or be deleted      |
| `withholding_unpaid`         | 400      | The day the fee was paid (`paid_on`) is missing                 | Record it first                            |
| `no_paid_filing`             | 409      | No paid withholdings F24 for the period                         | Prepare it and upload the receipt          |
| `coefficient_above_maximum`  | 400      | Rate above the ministerial maximum (art. 102(2) TUIR)           | Use at most the rate given                 |
| `not_a_small_asset`          | 400      | Full deduction only for assets up to €516.46 (art. 102(5) TUIR) | Depreciate the asset                       |
| `disposal_incomplete`        | 400      | Both `disposal_date` and `disposal_amount` are needed           | Pass both or neither                       |
| `in_service_before_purchase` | 400      | In service before it was bought                                 | Fix the dates                              |
| `too_many_assets`            | 400      | The maximum number of fixed assets is reached                   | Contact support                            |
| `pos_rt_link_exists`         | 409      | This POS is already linked to this RT                           | Use the existing link                      |
| `terminal_id_required`       | 400      | A physical POS (`pos_type` `00`) needs its `terminal_id`        | Add it, or use `01` for a virtual POS      |
| `link_already_filed`         | 409      | The link was already communicated to the Agenzia                | End it (`ended_on`) and add a new one      |
| `too_many_links`             | 400      | The maximum number of POS–RT links is reached                   | End the ones no longer in use              |

[Idempotency](/en/api/idempotency) errors are also described on that page.

## SDI rejections [#sdi-rejections]

An SDI rejection is not an API error: the send request succeeds, then SDI answers with a rejection receipt. The invoice moves to `rejected`, you receive the `invoice.rejected` webhook, and the codes are in `sdi.errors` (code and description) and `sdi.error_codes`. What they mean and how to fix them: [SDI rejection codes](/en/api/reference-data/sdi-errors).

Exception: `00404` on an invoice already sent means SDI already holds an accepted copy. The invoice **is issued**, does not become `rejected` and must not be resent. See [SDI lifecycle](/en/api/sdi-lifecycle).

## Errors in MCP tools [#errors-in-mcp-tools]

MCP tools return the same errors as a result with `isError: true`, with the `{ "error": { … } }` body in the text. Unknown or invalid arguments are refused earlier, with an `Input validation error: …` message that says what to fix: see [MCP server](/en/api/mcp#strict-arguments). In search mode, `call_tool` can answer `tool_not_found` and `tool_not_read_only`.
