--- title: "Gli errori dell’Open API di Fincanva" description: "Ogni codice di errore dell’Open API e del server MCP di Fincanva, con stato HTTP e significato, e la forma di una chiamata REST o di uno strumento MCP falliti." canonical_url: "https://fincanva.com/it/sviluppatori/open-api/gli-errori-dell-open-api-di-fincanva" last_updated: "2026-10-11" md_url: "https://fincanva.com/it/sviluppatori/open-api/gli-errori-dell-open-api-di-fincanva.md" --- # Gli errori dell’Open API di Fincanva Quando un’operazione fallisce, REST e MCP riportano lo stesso codice di errore con gli stessi dettagli, e il codice decide lo stato HTTP. ## Che cosa restituisce una chiamata REST fallita? Un corpo JSON con `status: false`, un `message`, il `code` dell’errore e un oggetto `details`: `unlockedBy` quando un piano superiore consentirebbe la chiamata, `resetsAt` quando una quota si ricaricherà, e `data` con ciò che è specifico del codice. Lo stato HTTP è quello del codice, dalla tabella qui sotto. Una volta identificato il chiamante, la risposta porta anche un’intestazione `X-Request-Id`. ## Che cosa restituisce una chiamata MCP fallita? Un risultato dello strumento con `isError: true`, il cui `structuredContent.error` porta lo stesso `code`, lo stesso `message` e gli stessi dettagli del corpo REST. ## Quali codici di errore può restituire un’operazione di Fincanva? Ogni codice, il suo stato HTTP e che cosa significa: - `invalid_input` — HTTP 422. I parametri non corrispondono allo schema dell’operazione; `details` elenca ogni problema con il suo campo. - `payload_too_large` — HTTP 413. Il corpo della richiesta è più grande di quanto un’operazione accetti; `details.maxBytes` indica il limite. Non è stato eseguito né addebitato nulla. - `result_too_large` — HTTP 422. La richiesta era valida, ma il suo risultato è più grande di quanto Fincanva conservi (`details.maxBytes`; `details.what` indica il valore). L’esecuzione viene rimborsata. Restringila (meno strumenti, un periodo più breve, meno passi) ed eseguila di nuovo. - `ambiguous` — HTTP 422. Un nome che hai indicato corrisponde a più strumenti; `details` elenca i candidati, quindi scegline uno e chiama di nuovo. - `not_resolved` — HTTP 422. Un nome che hai indicato non corrisponde a nessuno [strumento](/it/glossario/strumento) che Fincanva ha. - `insufficient_history` — HTTP 422. Gli strumenti non hanno abbastanza storico per il periodo o il [lookback](/it/glossario/finestra-di-calcolo) richiesto. - `unauthorized` — HTTP 401. La chiave API o il token di accesso manca, è scaduto o è stato revocato. - `plan_limit` — HTTP 403. Il tuo piano non include questa operazione o questa impostazione; `unlockedBy` indica il piano più basso che la include. - `toolset_disabled` — HTTP 403. Le impostazioni dell’utente per questa app collegata escludono l’operazione: la sua famiglia è disattivata, oppure l’app è in sola lettura e l’operazione crea o modifica qualcosa nella sua libreria. `details` indica la famiglia, oppure l’operazione e `readOnly`. Non è stato eseguito né addebitato nulla; l’utente può cambiare entrambe nelle Impostazioni di Fincanva, in App collegate. - `licence` — HTTP 403. Fincanva ha trattenuto la risposta perché i dati che rilascerebbe non possono uscire da Fincanva tramite l’API o MCP: lo vietano i termini di un fornitore, oppure sono dati che Fincanva protegge, come il suo storico dei prezzi di lungo periodo o la composizione storica degli indici, che non vengono mai restituiti riga per riga. `message` dice che cosa è stato trattenuto e che cosa è disponibile al suo posto, come statistiche di sintesi o cifre mensili calcolate su quei dati; `details` indica il dataset, la sua classe di licenza e il canale. - `quota_exhausted` — HTTP 429. La quota mensile di chiamate, di esecuzioni pesanti o di report di ricerca è esaurita; `resetsAt` indica la data in cui si azzera. - `rate_limited` — HTTP 429. Troppe chiamate nel minuto in corso: questa connessione, o questo account sommando le sue connessioni, ha raggiunto il limite al minuto del suo piano. `resetsAt` indica l’istante in cui il minuto si ricarica, e REST invia anche l’intestazione `Retry-After` in secondi. Attendi fino ad allora e ripeti la chiamata; non è stato eseguito né addebitato nulla. Quando un piano superiore consente più chiamate al minuto, `unlockedBy` indica il successivo che lo fa. - `not_found` — HTTP 404. L’operazione, oppure un elemento che hai indicato come un filtro, non esiste. - `conflict` — HTTP 409. L’elemento è cambiato dopo la chiamata a cui stai dando seguito, per esempio un elemento salvato modificato dopo che ne è stata emessa la proposta di sostituzione; non è stato scritto nulla. Rileggi l’elemento e ripeti la modifica. - `busy` — HTTP 503. Fincanva è al limite della capacità per questo tipo di esecuzione; non è stato addebitato nulla sulla tua quota, quindi riprova a breve. - `engine_failed` — HTTP 502. Il calcolo è fallito da parte di Fincanva; non è stato addebitato nulla sulla tua quota. - `internal` — HTTP 500. Un errore imprevisto da parte di Fincanva; non è stato addebitato nulla sulla tua quota. Fincanva ha uno scopo solo educativo e illustrativo: non è una consulenza finanziaria personalizzata, e i risultati passati o simulati non indicano quelli futuri. [Leggi l'Addendum ai Termini](https://fincanva.com/it/terms/addendum#section-3)