GetbeelDocs

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"
  }
}
  • 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

typeStatusWhen
authentication_error401Key or token missing, wrong, revoked, expired or suspended
permission_error402, 403A scope, a plan or the right mode (test or live) is missing
invalid_request_error400, 404, 409, 413, 415, 422The request is invalid, or invalid in the current state
not_found_error404The resource does not exist or is not in your team
rate_limit_error429Too many requests, see Rate limits
api_error500, 502, 503, 504Our 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

codeStatusMeaningWhat to do
missing_api_key401The Authorization header is missingSend Authorization: Bearer gb_…
invalid_api_key401Unknown or malformed keyCheck the key in Settings → API keys & MCP
api_key_revoked401Key revoked, or its creator left the teamCreate a new key
api_key_expired401Key expiredCreate a new key
api_key_suspended401The key's creator can no longer manage API keysHave a member with that permission create the key
invalid_token401OAuth token (gb_oat_…) expired, revoked or invalidRefresh it; if that fails, connect the app again
insufficient_scope403The required scope (named in the message) is missingCreate a key with that scope (keys cannot be edited) or reconnect the app
insufficient_permissions403The key's creator cannot add client companiesUse a key of a member with that permission
livemode_required403The operation changes real data and needs a live keyUse a gb_live_… key
test_mode_required403The receiving sandbox only takes test keysUse a gb_test_… key
company_not_eligible403Issuing invoices needs an Italian company profileComplete Settings → Company
invite_not_allowed403The key's creator cannot invite a commercialistaUse a key of a member with that permission
remove_not_allowed403The key's creator cannot remove that commercialistaAs above
sdi_addon_required402Live invoices (or Stripe sync) need the SDI planTurn it on in Settings → Usage & billing (for a client company, on the parent account); in test, use the sandbox
sdi_quota_exhausted402This month's SDI quota is used upUpgrade the SDI plan, or wait for next month
insufficient_balance402The 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_card409No card is saved yet, so there is no card to change (POST /billing/payment-method); application/problem+json like insufficient_balanceAdd a card with a top-up or in Settings → Billing & usage
not_pay_as_you_go409Usage, top-ups and card links are for pay-as-you-go accountsThe account (signed up before 13 November 2026) keeps its plan: see GET /usage
billing_permission_required403The key's creator cannot manage billingUse a key of a member with the billing permission
billed_to_parent403A 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_required402The paid product is needed (invoice processing, reconciliation)Pick a plan in Settings → Usage & billing
limit_reached402The plan's number of mailboxes is reachedDisconnect a mailbox or change plan

Request

codeStatusMeaningWhat to do
parameter_unknown400Unknown query parameter (the message lists the allowed ones) or, on PATCH /invoices/{id}, unknown body fieldRemove it or fix its name (for example cursor, not starting_after)
rate_limit_exceeded429Too many requests for the keyWait Retry-After seconds, then retry (Rate limits)
parameter_invalid400A parameter, field or header is invalid (see param)Fix the value
parameter_missing400A required parameter is missingAdd it
invalid_json400The body is not valid JSONSend valid JSON with Content-Type: application/json
invalid_multipart400The multipart body cannot be readSend multipart/form-data with a file field
file_url_unusable400, 413file_url is not a public https link answering 200 without redirects, or the file is over 50 MBUse a direct public link, or upload the file
payload_too_large413JSON body over 1 MB; XML over 5 MB (the SDI limit for one file); bank statement over 50 MB; receipt over 10 MBMake the file smaller
file_invalid413A filing receipt is over 10 MBUpload a smaller file
unsupported_media_type415Unsupported Content-TypeUse the one named in the message
unsupported_file_type415Unsupported bank statement type (for example a spreadsheet)Upload PDF, CSV, TXT, CBI, CAMT.053 or MT940
resource_missing404No resource with that id in your teamCheck the id (and Getbeel-Company or company_id)
company_not_found404The client company does not exist or is no longer availableUse an id from GET /companies
numbering_series_not_found404The numbering series does not existUse an id from GET /numbering-series
received_invoice_not_found400The received invoice given for the fixed asset is not in this companyUse an id from GET /received-invoices

Idempotency and concurrency

codeStatusMeaningWhat to do
idempotency_key_in_use409A request with the same Idempotency-Key is still runningRetry in a few seconds with the same key
idempotency_key_reused422The key was already used for a different requestUse a new key for a new request
invoice_send_in_progress409A send of this invoice is already runningDo not repeat it: read the status with GET /invoices/{id}
sync_in_progress409A sync of this bank connection is running or just ranRetry in a minute
filing_conflict409The filing is being prepared right nowRetry in a few seconds
reconciliation_conflict409The match changed meanwhileRead the reconciliation again and retry

Issued invoices and sending to SDI

codeStatusMeaningWhat to do
invoice_not_draft409Only a draft can be sent or edited: this one was already sentDo 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_sendable409A proforma is not sent to SDICreate a real invoice
invoice_not_rejected409Only an invoice rejected by SDI can be reopened, and not while an automatic fix is runningCheck 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_invalid422The invoice fails the local checks (FatturaPA XML or credit note rules)Fix what the message says
invoice_number_taken409An invoice with this number already existsLeave the number out (getbeel assigns the next one) or pick a free one
invoice_number_out_of_sequence422The number would jump ahead in the numberingUse the next number or one that fills a gap
company_profile_incomplete422The company profile lacks what is needed to issue (name, partita IVA or codice fiscale…)Complete Settings → Company
credit_exceeds_invoice422The credit note exceeds what is left to credit on the invoiceReduce the lines
invoice_not_issued409An invoice SDI accepted is needed (for a credit note, a payment, a link)Wait for the outcome, or pick another invoice
invoice_not_creditable409This invoice cannot be credited (proforma or credit note)Pick the original invoice
sdi_send_failed502The send did not start: the invoice stays a draftTry again later
internal_error500Internal 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

codeStatusMeaningWhat to do
quote_not_editable409The quote can no longer be editedCreate a new one
quote_converted409The quote already became an invoiceUse the invoice created
quote_invalid422The quote is not validFix what the message says
numbering_series_exists409A series with this prefix or suffix already existsPick another one
numbering_series_in_use409The series has invoices and cannot be changed or deletedCreate a new one
numbering_series_invalid422The series is not validFix what the message says
natura_required422An item at 0% VAT has no natura (SdI would refuse it: 00400)Give the natura (N1–N7) or a rate
customer_email_missing422The customer has no email addressPass to or add the email to the customer
email_failed502The email was not sentTry again later
invoice_already_paid409The invoice is already paidNothing to do
amount_exceeds_balance422The payment exceeds the amount dueReduce the amount
invoice_pdf_missing409The invoice PDF is not ready yetTry again shortly
invoice_not_copyable422The invoice cannot be repeated (for example a credit note)Use an ordinary invoice
recurring_invoice_exists409This invoice already repeatsChange the existing schedule
stripe_not_connected409No active Stripe connectionConnect Stripe (POST /connections/stripe)
stripe_mode_mismatch409The Stripe connection is in the other mode (test or live)Use a key of the same mode
stripe_error502Stripe errorTry again later

Banks, connections and documents

codeStatusMeaningWhat to do
bank_connection_inactive409The connection is not activeFinish the bank login or reconnect
bank_connection_requires_reconnect409The consent expired or was revokedReconnect the bank
bank_connection_conflict409The connection changed meanwhileRead it again and retry
bank_connection_limit409The maximum number of connected banks is reachedDisconnect one
bank_credentials_invalid422The Enable Banking app credentials are invalidCheck the credentials
redirect_url_not_allowed422The return URL is not allowedUse an allowed https URL
bank_daily_limit429The bank allows about four unattended updates a day, used upgetbeel retries by itself later
bank_error, bank_sync_failed502Bank or Enable Banking errorgetbeel retries; try again later
bank_unavailable503Banking service unavailableTry again later
connection_not_scannable409The mailbox cannot be scanned nowRead the message (connection expired, scan running)
reconnect_required409The mailbox authorization expired or was revoked; no scan was createdReconnect the mailbox in the app, then scan again
imap_connect_failed422IMAP connection failedCheck email, password, server and port (993)
rate_limited429Too many IMAP connection attemptsTry again later
unavailable503Feature not available on this deployment, or an external service is unreachableTry again later
internal500Internal error while connecting IMAPRetry; contact support with X-Request-Id
invoice_not_reviewable409The collected document is not waiting for reviewNothing to do
workflow_unavailable503Background processing is not availableTry again later
storage_error500, 503The file was not storedRetry
file_url_unreachable502, 504file_url could not be downloadedRetry or upload the file
file_empty400The file sent is emptySend the file again
credits_exhausted402No invoice credits left for the uploadBuy a pack or change plan in Usage & billing
processing_unavailable503The upload could not start reading the fileRetry
default_category409A default category cannot be deletedDelete another category, or rename this one
unknown_category422Not a category of this teamUse a slug from GET /categories
folder_exists409A Drive folder with that name exists therePick another name
folder_too_large503The Drive folder has too many files to delete at onceTry again: each call deletes more
statement_has_sent_autofatture409The statement holds autofatture at SDI: a fiscal recordKeep it; it cannot be deleted

SDI receiving and client companies

codeStatusMeaningWhat to do
company_not_ready422The company does not have what it needs to receive from SDI yetComplete the steps in GET /sdi-receiving
fiscal_id_taken409The partita IVA is already set up for receiving elsewhereContact support
invoice_unreadable422The test XML cannot be readFix the XML (for example the document date)
sdi_provider_unavailable502The receiving channel does not answerTry again later
company_nesting_not_allowed409A client company cannot have client companiesUse the parent account's key
already_member409The person is already in the teamNothing to do
already_invited409There is already an invitation for another roleRevoke it in the app

Filings, VAT, withholdings, fixed assets, POS–RT

codeStatusMeaningWhat to do
taxes_not_available400Taxes are available for Italian companies onlySet the country to Italy in the profile
vat_not_applicable400A regime without VAT (forfettario or minimi)No VAT registers or settlements to prepare
settings_missing400The VAT period (monthly or quarterly) is not setSet it in Taxes → Settings
settlements_missing400The quarter's saved settlements for the LIPE are missingSave the settlements named first
period_not_closed400The period is not overPrepare the filing after the period ends
period_not_started400The month has not startedPick a period that has started
nothing_due422Nothing is due in the periodNo F24 to prepare
filing_completed409The filing is already paid or filed and no longer changesNothing to do
file_missing400The receipt was not uploadedUpload it again
file_invalid500The generated LIPE file fails the official XSD checkContact support with X-Request-Id
too_many_documents400, 422Too many documents in the period to compute it herePick a shorter period or contact support
withholding_exists409The received invoice already has a withholdingUpdate that one
withholding_remitted409The withholding was already paid with an F24It can no longer change or be deleted
withholding_unpaid400The day the fee was paid (paid_on) is missingRecord it first
no_paid_filing409No paid withholdings F24 for the periodPrepare it and upload the receipt
coefficient_above_maximum400Rate above the ministerial maximum (art. 102(2) TUIR)Use at most the rate given
not_a_small_asset400Full deduction only for assets up to €516.46 (art. 102(5) TUIR)Depreciate the asset
disposal_incomplete400Both disposal_date and disposal_amount are neededPass both or neither
in_service_before_purchase400In service before it was boughtFix the dates
too_many_assets400The maximum number of fixed assets is reachedContact support
pos_rt_link_exists409This POS is already linked to this RTUse the existing link
terminal_id_required400A physical POS (pos_type 00) needs its terminal_idAdd it, or use 01 for a virtual POS
link_already_filed409The link was already communicated to the AgenziaEnd it (ended_on) and add a new one
too_many_links400The maximum number of POS–RT links is reachedEnd 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.

On this page