GetbeelDocs

Errori

La forma degli errori, gli stati HTTP e ogni codice che l'API può restituire, con cosa fare.

Ogni errore ha la stessa forma:

{
  "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 indica la categoria.
  • code è stabile: usalo nel codice per decidere cosa fare.
  • message è per le persone e può cambiare.
  • param, quando c'è, indica il campo, il parametro o l'header da correggere.

Ogni risposta, anche di successo, ha un header X-Request-Id (req_…). Indicalo quando contatti il supporto.

Tipi e stati HTTP

typeStatoQuando
authentication_error401Chiave o token mancante, errato, revocato, scaduto o sospeso
permission_error402, 403Manca uno scope, un piano o la modalità giusta (test o live)
invalid_request_error400, 404, 409, 413, 415, 422La richiesta non è valida, o non lo è nello stato attuale
not_found_error404La risorsa non esiste o non appartiene al tuo team
rate_limit_error429Troppe richieste, vedi Limiti di richieste
api_error500, 502, 503, 504Errore nostro o di un servizio esterno: riprova più tardi

Regola generale: correggi i 4xx prima di ripetere la richiesta (salvo 409 di concorrenza e 429, indicati sotto); ripeti 5xx ed errori di rete con un backoff e la stessa chiave di idempotenza.

Codici

L'elenco viene dal codice dell'API (ogni ApiError che un endpoint o uno strumento MCP può restituire).

Autenticazione e permessi

codeStatoSignificatoCosa fare
missing_api_key401Manca l'header AuthorizationInvia Authorization: Bearer gb_…
invalid_api_key401Chiave inesistente o malformataControlla la chiave in Impostazioni → Chiavi API e MCP
api_key_revoked401Chiave revocata, o chi l'ha creata non è più nel teamCrea una nuova chiave
api_key_expired401Chiave scadutaCrea una nuova chiave
api_key_suspended401Chi ha creato la chiave non può più gestire le chiaviFai creare la chiave a un membro con quel permesso
invalid_token401Token OAuth (gb_oat_…) scaduto, revocato o non validoRinnova con il refresh token; se non basta, ricollega l'app
insufficient_scope403Manca lo scope richiesto (indicato nel messaggio)Crea una chiave con quello scope (le chiavi non si modificano) o ricollega l'app
insufficient_permissions403Chi ha creato la chiave non può aggiungere aziende clientiUsa la chiave di un membro con quel permesso
livemode_required403L'operazione cambia dati reali e serve una chiave liveUsa una chiave gb_live_…
test_mode_required403La sandbox di ricezione accetta solo chiavi di testUsa una chiave gb_test_…
company_not_eligible403Per emettere fatture serve un profilo aziendale italianoCompleta Impostazioni → Azienda
invite_not_allowed403Chi ha creato la chiave non può invitare un commercialistaUsa la chiave di un membro con quel permesso
remove_not_allowed403Chi ha creato la chiave non può rimuovere quel commercialistaCome sopra
sdi_addon_required402Le fatture live (o la sincronizzazione Stripe) richiedono il piano SDIAttivalo in Impostazioni → Utilizzo e fatturazione (per un'azienda cliente, sull'account principale); in test usa la sandbox
sdi_quota_exhausted402La quota SDI del mese è finitaAumenta il piano SDI, o aspetta il mese successivo
insufficient_balance402Il saldo prepagato non copre l'azione (paghi quanto usi); la risposta è application/problem+json con balance_cents, required_cents e topup_url (per un'azienda cliente solo required_cents)Aggiungi credito da topup_url (Impostazioni → Fatturazione e utilizzo) o attiva la ricarica automatica
no_card409Non c'è ancora una carta salvata da cambiare (POST /billing/payment-method); application/problem+json come insufficient_balanceAggiungi una carta con una ricarica o in Impostazioni → Fatturazione e utilizzo
not_pay_as_you_go409Consumi, ricariche e carta valgono per gli account che pagano quanto usanoL'account (registrato prima del 13 novembre 2026) mantiene il suo piano: vedi GET /usage
billing_permission_required403Chi ha creato la chiave non può gestire la fatturazioneUsa la chiave di un membro con il permesso di fatturazione
billed_to_parent403Un'azienda cliente paga dal saldo del gestore (anche saldo e consumi: con la chiave dell'azienda non si leggono)Aggiungi credito dall'account principale
subscription_required402Serve il prodotto a pagamento (elaborazione fatture, riconciliazione)Scegli un piano in Impostazioni → Utilizzo e fatturazione
limit_reached402Raggiunto il numero di caselle email del pianoScollega una casella o cambia piano

Richiesta

codeStatoSignificatoCosa fare
parameter_unknown400Parametro di query sconosciuto (il messaggio elenca quelli ammessi) o, su PATCH /invoices/{id}, campo del corpo sconosciutoToglilo o correggine il nome (per esempio cursor, non starting_after)
rate_limit_exceeded429Troppe richieste per la chiaveAttendi i secondi di Retry-After, poi riprova (Limiti di richieste)
parameter_invalid400Un parametro, un campo o un header non è valido (vedi param)Correggi il valore
parameter_missing400Manca un parametro obbligatorioAggiungilo
invalid_json400Il corpo non è JSON validoInvia JSON valido con Content-Type: application/json
invalid_multipart400Il corpo multipart non si leggeInvia multipart/form-data con il campo file
file_url_unusable400, 413file_url non è un link https pubblico che risponde 200 senza redirect, o il file supera 50 MBUsa un link diretto e pubblico, o carica il file
payload_too_large413Corpo JSON oltre 1 MB; XML oltre 5 MB (il limite SDI per un file); estratto conto oltre 50 MB; ricevuta oltre 10 MBRiduci il file
file_invalid413La ricevuta di un adempimento supera 10 MBCarica un file più piccolo
unsupported_media_type415Content-Type non supportatoUsa quello indicato nel messaggio
unsupported_file_type415Tipo di estratto conto non supportato (per esempio un foglio di calcolo)Carica PDF, CSV, TXT, CBI, CAMT.053 o MT940
resource_missing404Nessuna risorsa con quell'id nel tuo teamControlla l'id (e Getbeel-Company o company_id)
company_not_found404L'azienda cliente indicata non esiste o non è più disponibileUsa un id da GET /companies
numbering_series_not_found404Il sezionale indicato non esisteUsa un id da GET /numbering-series
received_invoice_not_found400La fattura ricevuta indicata per il cespite non esiste in questa aziendaUsa un id da GET /received-invoices

Idempotenza e concorrenza

codeStatoSignificatoCosa fare
idempotency_key_in_use409Una richiesta con la stessa Idempotency-Key è ancora in corsoRiprova tra qualche secondo con la stessa chiave
idempotency_key_reused422La chiave è già stata usata per una richiesta diversaUsa una chiave nuova per una richiesta nuova
invoice_send_in_progress409Un invio di questa fattura è già in corsoNon ripetere: leggi lo stato con GET /invoices/{id}
sync_in_progress409Un aggiornamento di questa banca è in corso o appena terminatoRiprova tra un minuto
filing_conflict409L'adempimento è in preparazione in questo momentoRiprova tra qualche secondo
reconciliation_conflict409L'abbinamento è cambiato nel frattempoRileggi la riconciliazione e riprova

Fatture emesse e invio allo SDI

codeStatoSignificatoCosa fare
invoice_not_draft409Solo una bozza si può inviare o modificare: questa è già stata inviataNon reinviarla: leggi lo stato e l'esito in sdi (ciclo di vita SDI). Con PATCH: una fattura scartata si riapre prima (POST /invoices/{id}/reopen), una inviata si corregge con una nota di credito
invoice_not_sendable409Una fattura proforma non si invia allo SDICrea una fattura vera
invoice_not_rejected409Si può riaprire solo una fattura scartata dallo SDI, e non mentre una correzione automatica è in corsoControlla lo stato: una fattura delivered, not_delivered o con 00404 è emessa e non si riapre. Una draft si modifica così com'è (PATCH); una consegnata si corregge con una nota di credito
invoice_invalid422La fattura non passa i controlli locali (XML FatturaPA o regole della nota di credito)Correggi quanto indicato nel messaggio
invoice_number_taken409Esiste già una fattura con questo numeroOmetti il numero (getbeel assegna il successivo) o scegline uno libero
invoice_number_out_of_sequence422Il numero salterebbe avanti nella numerazioneUsa il prossimo numero o uno che colma un buco
company_profile_incomplete422Il profilo aziendale non ha i dati per emettere (nome, partita IVA o codice fiscale…)Completa Impostazioni → Azienda
credit_exceeds_invoice422La nota di credito supera quanto resta da accreditare sulla fatturaRiduci le righe
invoice_not_issued409Serve una fattura accettata dallo SDI (per una nota di credito, un pagamento, un link)Aspetta l'esito, o scegli un'altra fattura
invoice_not_creditable409Questa fattura non si può accreditare (proforma o nota di credito)Scegli la fattura originale
sdi_send_failed502L'invio non è partito: la fattura resta in bozzaRiprova più tardi
internal_error500Errore interno (per esempio creazione della fattura non riuscita)Riprova; se persiste, contatta il supporto con X-Request-Id

Uno scarto dello SDI non è un errore dell'API: l'invio va a buon fine, poi lo SDI risponde. Vedi sotto.

Preventivi, sezionali e incasso

codeStatoSignificatoCosa fare
quote_not_editable409Il preventivo non è più modificabileCreane uno nuovo
quote_converted409Il preventivo è già diventato fatturaUsa la fattura creata
quote_invalid422Il preventivo non è validoCorreggi quanto indicato
numbering_series_exists409Esiste già un sezionale con questo prefisso o suffissoScegline un altro
numbering_series_in_use409Il sezionale ha fatture e non si può cambiare o eliminareCreane uno nuovo
numbering_series_invalid422Il sezionale non è validoCorreggi quanto indicato
natura_required422Un articolo con IVA 0% non ha la natura (SdI la scarterebbe: 00400)Indica la natura (N1–N7) o un'aliquota
customer_email_missing422Il cliente non ha un indirizzo emailPassa to o aggiungi l'email al cliente
email_failed502L'email non è partitaRiprova più tardi
invoice_already_paid409La fattura è già pagataNessuna azione
amount_exceeds_balance422Il pagamento supera il dovutoRiduci l'importo
invoice_pdf_missing409Il PDF della fattura non è ancora prontoRiprova tra poco
invoice_not_copyable422La fattura non si può ripetere (per esempio una nota di credito)Usa una fattura ordinaria
recurring_invoice_exists409Questa fattura ha già una ripetizioneModifica quella esistente
stripe_not_connected409Nessun collegamento Stripe attivoCollega Stripe (POST /connections/stripe)
stripe_mode_mismatch409Il collegamento Stripe è in un'altra modalità (test o live)Usa la chiave della stessa modalità
stripe_error502Errore di StripeRiprova più tardi

Banca, connessioni e documenti

codeStatoSignificatoCosa fare
bank_connection_inactive409Il collegamento non è attivoCompleta l'accesso alla banca o ricollegala
bank_connection_requires_reconnect409Il consenso è scaduto o revocatoRicollega la banca
bank_connection_conflict409Il collegamento è cambiato nel frattempoRileggi e riprova
bank_connection_limit409Raggiunto il numero massimo di banche collegateScollegane una
bank_credentials_invalid422Credenziali dell'app Enable Banking non valideControlla le credenziali
redirect_url_not_allowed422L'URL di ritorno non è ammessoUsa un URL https consentito
bank_daily_limit429La banca ammette circa quattro aggiornamenti al giorno, esauritigetbeel riprova da solo più tardi
bank_error, bank_sync_failed502Errore della banca o di Enable Bankinggetbeel riprova; riprova più tardi
bank_unavailable503Servizio bancario non disponibileRiprova più tardi
connection_not_scannable409La casella non si può scansionare oraLeggi il messaggio (collegamento scaduto, scansione in corso)
reconnect_required409Autorizzazione della casella scaduta o revocata; nessuna scansione creataRicollega la casella nell'app, poi scansiona di nuovo
imap_connect_failed422Connessione IMAP non riuscitaControlla email, password, server e porta (993)
rate_limited429Troppi tentativi di collegamento IMAPRiprova più tardi
unavailable503Funzione non disponibile su questa installazione, o servizio esterno non raggiungibileRiprova più tardi
internal500Errore interno nel collegamento IMAPRiprova; contatta il supporto con X-Request-Id
invoice_not_reviewable409Il documento raccolto non è in attesa di verificaNessuna azione
workflow_unavailable503L'elaborazione in background non è disponibileRiprova più tardi
storage_error500, 503Il file non è stato salvatoRiprova
file_url_unreachable502, 504Non è stato possibile scaricare file_urlRiprova o carica il file
file_empty400Il file inviato è vuotoInvia di nuovo il file
credits_exhausted402Crediti fattura esauriti per il caricamentoAcquista un pacchetto o cambia piano in Utilizzo e fatturazione
processing_unavailable503Il caricamento non è riuscito ad avviare la lettura del fileRiprova
default_category409Una categoria predefinita non si eliminaElimina un'altra categoria, o rinomina questa
unknown_category422Non è una categoria di questo teamUsa uno slug da GET /categories
folder_exists409Lì esiste già una cartella del Drive con quel nomeScegli un altro nome
folder_too_large503La cartella del Drive ha troppi file da eliminare in una voltaRiprova: ogni chiamata ne elimina altri
statement_has_sent_autofatture409L'estratto conto contiene autofatture allo SDI: è un documento fiscaleConservalo; non si può eliminare

Ricezione SDI e aziende clienti

codeStatoSignificatoCosa fare
company_not_ready422L'azienda non ha ancora i dati per ricevere dallo SDICompleta i passaggi in GET /sdi-receiving
fiscal_id_taken409La partita IVA è già configurata per la ricezione altroveContatta il supporto
invoice_unreadable422L'XML di prova non si leggeCorreggi l'XML (per esempio la data del documento)
sdi_provider_unavailable502Il canale di ricezione non rispondeRiprova più tardi
company_nesting_not_allowed409Un'azienda cliente non può avere aziende clientiUsa la chiave dell'account principale
already_member409La persona fa già parte del teamNessuna azione
already_invited409Esiste già un invito per un altro ruoloRevoca l'invito nell'app

Adempimenti, IVA, ritenute, cespiti, POS–RT

codeStatoSignificatoCosa fare
taxes_not_available400Le imposte sono disponibili solo per aziende italianeImposta il paese Italia nel profilo
vat_not_applicable400Regime senza IVA (forfettario o minimi)Nessun registro o liquidazione IVA da preparare
settings_missing400Manca la periodicità IVA (mensile o trimestrale)Impostala in Imposte → Impostazioni
settlements_missing400Mancano le liquidazioni salvate del trimestre per la LIPESalva prima le liquidazioni indicate
period_not_closed400Il periodo non è finitoPrepara l'adempimento dopo la fine del periodo
period_not_started400Il mese non è ancora iniziatoScegli un periodo iniziato
nothing_due422Nel periodo non c'è niente da versareNessun F24 da preparare
filing_completed409L'adempimento è già pagato o inviato e non cambia piùNessuna azione
file_missing400La ricevuta non è stata caricataRipeti il caricamento
file_invalid500Il file LIPE generato non passa il controllo XSD ufficialeContatta il supporto con X-Request-Id
too_many_documents400, 422Troppi documenti nel periodo per calcolarlo quiScegli un periodo più breve o contatta il supporto
withholding_exists409La fattura ricevuta ha già una ritenutaAggiorna quella
withholding_remitted409La ritenuta è già stata versata con un F24Non si può più cambiare né eliminare
withholding_unpaid400Manca il giorno del pagamento del compenso (paid_on)Registralo prima
no_paid_filing409Nessun F24 delle ritenute pagato per il periodoPreparalo e carica la quietanza
coefficient_above_maximum400Coefficiente oltre il massimo ministeriale (art. 102 c. 2 TUIR)Usa al massimo il coefficiente indicato
not_a_small_asset400Deduzione integrale solo per beni fino a 516,46 € (art. 102 c. 5 TUIR)Ammortizza il bene
disposal_incomplete400Serve sia disposal_date sia disposal_amountPassali entrambi o nessuno
in_service_before_purchase400Entrata in funzione prima dell'acquistoCorreggi le date
too_many_assets400Raggiunto il numero massimo di cespitiContatta il supporto
pos_rt_link_exists409Questo POS è già collegato a questo RTUsa il collegamento esistente
terminal_id_required400Un POS fisico (pos_type 00) richiede il suo terminal_idAggiungilo, o usa 01 per un POS virtuale
link_already_filed409Il collegamento è già stato comunicato all'AgenziaChiudilo (ended_on) e aggiungine uno nuovo
too_many_links400Raggiunto il numero massimo di collegamenti POS–RTChiudi quelli non più in uso

Gli errori dell'idempotenza sono descritti anche in quella pagina.

Scarti dello SDI

Uno scarto dello SDI non è un errore dell'API: la richiesta di invio va a buon fine, poi lo SDI risponde con una ricevuta di scarto. La fattura passa a rejected, ricevi il webhook invoice.rejected e i codici sono in sdi.errors (codice e descrizione) e sdi.error_codes. Cosa significano e come correggerli: Codici di scarto SDI.

Eccezione: 00404 su una fattura già inviata significa che lo SDI ha già una copia accettata. La fattura è emessa, non diventa rejected e non va reinviata. Vedi ciclo di vita SDI.

Errori negli strumenti MCP

Gli strumenti MCP restituiscono gli stessi errori come risultato con isError: true, con il corpo { "error": { … } } nel testo. Gli argomenti sconosciuti o non validi sono rifiutati prima, con un messaggio Input validation error: … che dice cosa correggere: vedi Server MCP. In modalità ricerca, call_tool può rispondere tool_not_found e tool_not_read_only.

In questa pagina