Errors
The error shape, HTTP statuses and every code the API can return, with what to do.
Every error has the same shape:
{
"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"
}
}typeis the category.codeis stable: use it in your code to decide what to do.messageis 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
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 |
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 409s and 429, listed below); retry 5xx and network errors with backoff and the same idempotency key.
Codes
The list comes from the API code (every ApiError an endpoint or an MCP tool can return).
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
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) |
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
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
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). 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
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
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
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
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 errors are also described on that page.
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.
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.
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. In search mode, call_tool can answer tool_not_found and tool_not_read_only.