# Errori (https://docs.getbeel.com/it/api/errors)

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

Ogni errore ha la stessa forma:

```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` 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 [#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](/it/api/rate-limits) |
| `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](/it/api/idempotency).

## Codici [#codici]

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

### Autenticazione e permessi [#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 [#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](/it/api/rate-limits)) |
| `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 [#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 [#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](/it/api/sdi-lifecycle)). 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 [#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 [#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 [#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 [#adempimenti-iva-ritenute-cespiti-posrt]

| `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](/it/api/idempotency) sono descritti anche in quella pagina.

## Scarti dello SDI [#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](/it/api/reference-data/sdi-errors).

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](/it/api/sdi-lifecycle).

## Errori negli strumenti MCP [#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](/it/api/mcp#argomenti-rigorosi). In modalità ricerca, `call_tool` può rispondere `tool_not_found` e `tool_not_read_only`.
