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"
}
}typeindica 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
type | Stato | Quando |
|---|---|---|
authentication_error | 401 | Chiave o token mancante, errato, revocato, scaduto o sospeso |
permission_error | 402, 403 | Manca uno scope, un piano o la modalità giusta (test o live) |
invalid_request_error | 400, 404, 409, 413, 415, 422 | La richiesta non è valida, o non lo è nello stato attuale |
not_found_error | 404 | La risorsa non esiste o non appartiene al tuo team |
rate_limit_error | 429 | Troppe richieste, vedi Limiti di richieste |
api_error | 500, 502, 503, 504 | Errore 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
code | Stato | Significato | Cosa fare |
|---|---|---|---|
missing_api_key | 401 | Manca l'header Authorization | Invia Authorization: Bearer gb_… |
invalid_api_key | 401 | Chiave inesistente o malformata | Controlla la chiave in Impostazioni → Chiavi API e MCP |
api_key_revoked | 401 | Chiave revocata, o chi l'ha creata non è più nel team | Crea una nuova chiave |
api_key_expired | 401 | Chiave scaduta | Crea una nuova chiave |
api_key_suspended | 401 | Chi ha creato la chiave non può più gestire le chiavi | Fai creare la chiave a un membro con quel permesso |
invalid_token | 401 | Token OAuth (gb_oat_…) scaduto, revocato o non valido | Rinnova con il refresh token; se non basta, ricollega l'app |
insufficient_scope | 403 | Manca lo scope richiesto (indicato nel messaggio) | Crea una chiave con quello scope (le chiavi non si modificano) o ricollega l'app |
insufficient_permissions | 403 | Chi ha creato la chiave non può aggiungere aziende clienti | Usa la chiave di un membro con quel permesso |
livemode_required | 403 | L'operazione cambia dati reali e serve una chiave live | Usa una chiave gb_live_… |
test_mode_required | 403 | La sandbox di ricezione accetta solo chiavi di test | Usa una chiave gb_test_… |
company_not_eligible | 403 | Per emettere fatture serve un profilo aziendale italiano | Completa Impostazioni → Azienda |
invite_not_allowed | 403 | Chi ha creato la chiave non può invitare un commercialista | Usa la chiave di un membro con quel permesso |
remove_not_allowed | 403 | Chi ha creato la chiave non può rimuovere quel commercialista | Come sopra |
sdi_addon_required | 402 | Le fatture live (o la sincronizzazione Stripe) richiedono il piano SDI | Attivalo in Impostazioni → Utilizzo e fatturazione (per un'azienda cliente, sull'account principale); in test usa la sandbox |
sdi_quota_exhausted | 402 | La quota SDI del mese è finita | Aumenta il piano SDI, o aspetta il mese successivo |
insufficient_balance | 402 | Il 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_card | 409 | Non c'è ancora una carta salvata da cambiare (POST /billing/payment-method); application/problem+json come insufficient_balance | Aggiungi una carta con una ricarica o in Impostazioni → Fatturazione e utilizzo |
not_pay_as_you_go | 409 | Consumi, ricariche e carta valgono per gli account che pagano quanto usano | L'account (registrato prima del 13 novembre 2026) mantiene il suo piano: vedi GET /usage |
billing_permission_required | 403 | Chi ha creato la chiave non può gestire la fatturazione | Usa la chiave di un membro con il permesso di fatturazione |
billed_to_parent | 403 | Un'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_required | 402 | Serve il prodotto a pagamento (elaborazione fatture, riconciliazione) | Scegli un piano in Impostazioni → Utilizzo e fatturazione |
limit_reached | 402 | Raggiunto il numero di caselle email del piano | Scollega una casella o cambia piano |
Richiesta
code | Stato | Significato | Cosa fare |
|---|---|---|---|
parameter_unknown | 400 | Parametro di query sconosciuto (il messaggio elenca quelli ammessi) o, su PATCH /invoices/{id}, campo del corpo sconosciuto | Toglilo o correggine il nome (per esempio cursor, non starting_after) |
rate_limit_exceeded | 429 | Troppe richieste per la chiave | Attendi i secondi di Retry-After, poi riprova (Limiti di richieste) |
parameter_invalid | 400 | Un parametro, un campo o un header non è valido (vedi param) | Correggi il valore |
parameter_missing | 400 | Manca un parametro obbligatorio | Aggiungilo |
invalid_json | 400 | Il corpo non è JSON valido | Invia JSON valido con Content-Type: application/json |
invalid_multipart | 400 | Il corpo multipart non si legge | Invia multipart/form-data con il campo file |
file_url_unusable | 400, 413 | file_url non è un link https pubblico che risponde 200 senza redirect, o il file supera 50 MB | Usa un link diretto e pubblico, o carica il file |
payload_too_large | 413 | Corpo JSON oltre 1 MB; XML oltre 5 MB (il limite SDI per un file); estratto conto oltre 50 MB; ricevuta oltre 10 MB | Riduci il file |
file_invalid | 413 | La ricevuta di un adempimento supera 10 MB | Carica un file più piccolo |
unsupported_media_type | 415 | Content-Type non supportato | Usa quello indicato nel messaggio |
unsupported_file_type | 415 | Tipo di estratto conto non supportato (per esempio un foglio di calcolo) | Carica PDF, CSV, TXT, CBI, CAMT.053 o MT940 |
resource_missing | 404 | Nessuna risorsa con quell'id nel tuo team | Controlla l'id (e Getbeel-Company o company_id) |
company_not_found | 404 | L'azienda cliente indicata non esiste o non è più disponibile | Usa un id da GET /companies |
numbering_series_not_found | 404 | Il sezionale indicato non esiste | Usa un id da GET /numbering-series |
received_invoice_not_found | 400 | La fattura ricevuta indicata per il cespite non esiste in questa azienda | Usa un id da GET /received-invoices |
Idempotenza e concorrenza
code | Stato | Significato | Cosa fare |
|---|---|---|---|
idempotency_key_in_use | 409 | Una richiesta con la stessa Idempotency-Key è ancora in corso | Riprova tra qualche secondo con la stessa chiave |
idempotency_key_reused | 422 | La chiave è già stata usata per una richiesta diversa | Usa una chiave nuova per una richiesta nuova |
invoice_send_in_progress | 409 | Un invio di questa fattura è già in corso | Non ripetere: leggi lo stato con GET /invoices/{id} |
sync_in_progress | 409 | Un aggiornamento di questa banca è in corso o appena terminato | Riprova tra un minuto |
filing_conflict | 409 | L'adempimento è in preparazione in questo momento | Riprova tra qualche secondo |
reconciliation_conflict | 409 | L'abbinamento è cambiato nel frattempo | Rileggi la riconciliazione e riprova |
Fatture emesse e invio allo SDI
code | Stato | Significato | Cosa fare |
|---|---|---|---|
invoice_not_draft | 409 | Solo una bozza si può inviare o modificare: questa è già stata inviata | Non 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_sendable | 409 | Una fattura proforma non si invia allo SDI | Crea una fattura vera |
invoice_not_rejected | 409 | Si può riaprire solo una fattura scartata dallo SDI, e non mentre una correzione automatica è in corso | Controlla 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_invalid | 422 | La fattura non passa i controlli locali (XML FatturaPA o regole della nota di credito) | Correggi quanto indicato nel messaggio |
invoice_number_taken | 409 | Esiste già una fattura con questo numero | Ometti il numero (getbeel assegna il successivo) o scegline uno libero |
invoice_number_out_of_sequence | 422 | Il numero salterebbe avanti nella numerazione | Usa il prossimo numero o uno che colma un buco |
company_profile_incomplete | 422 | Il profilo aziendale non ha i dati per emettere (nome, partita IVA o codice fiscale…) | Completa Impostazioni → Azienda |
credit_exceeds_invoice | 422 | La nota di credito supera quanto resta da accreditare sulla fattura | Riduci le righe |
invoice_not_issued | 409 | Serve una fattura accettata dallo SDI (per una nota di credito, un pagamento, un link) | Aspetta l'esito, o scegli un'altra fattura |
invoice_not_creditable | 409 | Questa fattura non si può accreditare (proforma o nota di credito) | Scegli la fattura originale |
sdi_send_failed | 502 | L'invio non è partito: la fattura resta in bozza | Riprova più tardi |
internal_error | 500 | Errore 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
code | Stato | Significato | Cosa fare |
|---|---|---|---|
quote_not_editable | 409 | Il preventivo non è più modificabile | Creane uno nuovo |
quote_converted | 409 | Il preventivo è già diventato fattura | Usa la fattura creata |
quote_invalid | 422 | Il preventivo non è valido | Correggi quanto indicato |
numbering_series_exists | 409 | Esiste già un sezionale con questo prefisso o suffisso | Scegline un altro |
numbering_series_in_use | 409 | Il sezionale ha fatture e non si può cambiare o eliminare | Creane uno nuovo |
numbering_series_invalid | 422 | Il sezionale non è valido | Correggi quanto indicato |
natura_required | 422 | Un articolo con IVA 0% non ha la natura (SdI la scarterebbe: 00400) | Indica la natura (N1–N7) o un'aliquota |
customer_email_missing | 422 | Il cliente non ha un indirizzo email | Passa to o aggiungi l'email al cliente |
email_failed | 502 | L'email non è partita | Riprova più tardi |
invoice_already_paid | 409 | La fattura è già pagata | Nessuna azione |
amount_exceeds_balance | 422 | Il pagamento supera il dovuto | Riduci l'importo |
invoice_pdf_missing | 409 | Il PDF della fattura non è ancora pronto | Riprova tra poco |
invoice_not_copyable | 422 | La fattura non si può ripetere (per esempio una nota di credito) | Usa una fattura ordinaria |
recurring_invoice_exists | 409 | Questa fattura ha già una ripetizione | Modifica quella esistente |
stripe_not_connected | 409 | Nessun collegamento Stripe attivo | Collega Stripe (POST /connections/stripe) |
stripe_mode_mismatch | 409 | Il collegamento Stripe è in un'altra modalità (test o live) | Usa la chiave della stessa modalità |
stripe_error | 502 | Errore di Stripe | Riprova più tardi |
Banca, connessioni e documenti
code | Stato | Significato | Cosa fare |
|---|---|---|---|
bank_connection_inactive | 409 | Il collegamento non è attivo | Completa l'accesso alla banca o ricollegala |
bank_connection_requires_reconnect | 409 | Il consenso è scaduto o revocato | Ricollega la banca |
bank_connection_conflict | 409 | Il collegamento è cambiato nel frattempo | Rileggi e riprova |
bank_connection_limit | 409 | Raggiunto il numero massimo di banche collegate | Scollegane una |
bank_credentials_invalid | 422 | Credenziali dell'app Enable Banking non valide | Controlla le credenziali |
redirect_url_not_allowed | 422 | L'URL di ritorno non è ammesso | Usa un URL https consentito |
bank_daily_limit | 429 | La banca ammette circa quattro aggiornamenti al giorno, esauriti | getbeel riprova da solo più tardi |
bank_error, bank_sync_failed | 502 | Errore della banca o di Enable Banking | getbeel riprova; riprova più tardi |
bank_unavailable | 503 | Servizio bancario non disponibile | Riprova più tardi |
connection_not_scannable | 409 | La casella non si può scansionare ora | Leggi il messaggio (collegamento scaduto, scansione in corso) |
reconnect_required | 409 | Autorizzazione della casella scaduta o revocata; nessuna scansione creata | Ricollega la casella nell'app, poi scansiona di nuovo |
imap_connect_failed | 422 | Connessione IMAP non riuscita | Controlla email, password, server e porta (993) |
rate_limited | 429 | Troppi tentativi di collegamento IMAP | Riprova più tardi |
unavailable | 503 | Funzione non disponibile su questa installazione, o servizio esterno non raggiungibile | Riprova più tardi |
internal | 500 | Errore interno nel collegamento IMAP | Riprova; contatta il supporto con X-Request-Id |
invoice_not_reviewable | 409 | Il documento raccolto non è in attesa di verifica | Nessuna azione |
workflow_unavailable | 503 | L'elaborazione in background non è disponibile | Riprova più tardi |
storage_error | 500, 503 | Il file non è stato salvato | Riprova |
file_url_unreachable | 502, 504 | Non è stato possibile scaricare file_url | Riprova o carica il file |
file_empty | 400 | Il file inviato è vuoto | Invia di nuovo il file |
credits_exhausted | 402 | Crediti fattura esauriti per il caricamento | Acquista un pacchetto o cambia piano in Utilizzo e fatturazione |
processing_unavailable | 503 | Il caricamento non è riuscito ad avviare la lettura del file | Riprova |
default_category | 409 | Una categoria predefinita non si elimina | Elimina un'altra categoria, o rinomina questa |
unknown_category | 422 | Non è una categoria di questo team | Usa uno slug da GET /categories |
folder_exists | 409 | Lì esiste già una cartella del Drive con quel nome | Scegli un altro nome |
folder_too_large | 503 | La cartella del Drive ha troppi file da eliminare in una volta | Riprova: ogni chiamata ne elimina altri |
statement_has_sent_autofatture | 409 | L'estratto conto contiene autofatture allo SDI: è un documento fiscale | Conservalo; non si può eliminare |
Ricezione SDI e aziende clienti
code | Stato | Significato | Cosa fare |
|---|---|---|---|
company_not_ready | 422 | L'azienda non ha ancora i dati per ricevere dallo SDI | Completa i passaggi in GET /sdi-receiving |
fiscal_id_taken | 409 | La partita IVA è già configurata per la ricezione altrove | Contatta il supporto |
invoice_unreadable | 422 | L'XML di prova non si legge | Correggi l'XML (per esempio la data del documento) |
sdi_provider_unavailable | 502 | Il canale di ricezione non risponde | Riprova più tardi |
company_nesting_not_allowed | 409 | Un'azienda cliente non può avere aziende clienti | Usa la chiave dell'account principale |
already_member | 409 | La persona fa già parte del team | Nessuna azione |
already_invited | 409 | Esiste già un invito per un altro ruolo | Revoca l'invito nell'app |
Adempimenti, IVA, ritenute, cespiti, POS–RT
code | Stato | Significato | Cosa fare |
|---|---|---|---|
taxes_not_available | 400 | Le imposte sono disponibili solo per aziende italiane | Imposta il paese Italia nel profilo |
vat_not_applicable | 400 | Regime senza IVA (forfettario o minimi) | Nessun registro o liquidazione IVA da preparare |
settings_missing | 400 | Manca la periodicità IVA (mensile o trimestrale) | Impostala in Imposte → Impostazioni |
settlements_missing | 400 | Mancano le liquidazioni salvate del trimestre per la LIPE | Salva prima le liquidazioni indicate |
period_not_closed | 400 | Il periodo non è finito | Prepara l'adempimento dopo la fine del periodo |
period_not_started | 400 | Il mese non è ancora iniziato | Scegli un periodo iniziato |
nothing_due | 422 | Nel periodo non c'è niente da versare | Nessun F24 da preparare |
filing_completed | 409 | L'adempimento è già pagato o inviato e non cambia più | Nessuna azione |
file_missing | 400 | La ricevuta non è stata caricata | Ripeti il caricamento |
file_invalid | 500 | Il file LIPE generato non passa il controllo XSD ufficiale | Contatta il supporto con X-Request-Id |
too_many_documents | 400, 422 | Troppi documenti nel periodo per calcolarlo qui | Scegli un periodo più breve o contatta il supporto |
withholding_exists | 409 | La fattura ricevuta ha già una ritenuta | Aggiorna quella |
withholding_remitted | 409 | La ritenuta è già stata versata con un F24 | Non si può più cambiare né eliminare |
withholding_unpaid | 400 | Manca il giorno del pagamento del compenso (paid_on) | Registralo prima |
no_paid_filing | 409 | Nessun F24 delle ritenute pagato per il periodo | Preparalo e carica la quietanza |
coefficient_above_maximum | 400 | Coefficiente oltre il massimo ministeriale (art. 102 c. 2 TUIR) | Usa al massimo il coefficiente indicato |
not_a_small_asset | 400 | Deduzione integrale solo per beni fino a 516,46 € (art. 102 c. 5 TUIR) | Ammortizza il bene |
disposal_incomplete | 400 | Serve sia disposal_date sia disposal_amount | Passali entrambi o nessuno |
in_service_before_purchase | 400 | Entrata in funzione prima dell'acquisto | Correggi le date |
too_many_assets | 400 | Raggiunto il numero massimo di cespiti | Contatta il supporto |
pos_rt_link_exists | 409 | Questo POS è già collegato a questo RT | Usa il collegamento esistente |
terminal_id_required | 400 | Un POS fisico (pos_type 00) richiede il suo terminal_id | Aggiungilo, o usa 01 per un POS virtuale |
link_already_filed | 409 | Il collegamento è già stato comunicato all'Agenzia | Chiudilo (ended_on) e aggiungine uno nuovo |
too_many_links | 400 | Raggiunto il numero massimo di collegamenti POS–RT | Chiudi 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.