Risoluzione dei problemi relativi agli errori dell'API di Pleo

La richiesta non è valida o non supera la convalida.

• Leggi il corpo della risposta per individuare i campi mancanti o i valori non validi.
• Confronta la tua richiesta con la documentazione dell'endpoint. Controlla i campi obbligatori, la struttura della richiesta, i formati delle date e i valori consentiti.
• Correggi il problema individuato e riprova con la richiesta.

Impossibile autenticare la richiesta.

• Abbina le credenziali all'API e all'ambiente. Verifica l'host della richiesta nella documentazione per sviluppatori. Non mescolare le credenziali della nuova API con quelle della API Legacy, né le credenziali di staging con quelle di produzione.
• Controlla l'intestazione di autorizzazione ("Authorization"). Le nuove chiavi API usano l'autenticazione Basic, con la chiave come nome utente e una password vuota. I token di accesso OAuth usano l'autenticazione Bearer. Segui la documentazione della API Legacy per i token legacy. Rimuovi eventuali spazi o interruzioni di riga accidentali dalle credenziali.
• Controlla lo stato delle credenziali. Verifica che non siano scadute o revocate. Per OAuth, usa il token di accesso, non il token di aggiornamento, e assicurati che il flusso di aggiornamento del token funzioni correttamente.

La richiesta è stata autenticata, ma l'accesso non è consentito.

• Controlla gli scope. Confronta gli scope assegnati alle tue credenziali con quelli richiesti dall'endpoint. Se non riesci a visualizzarli, chiedi alla persona che gestisce le credenziali di confermarteli.
• Controlla l'azienda e l'ambiente. Le credenziali devono corrispondere all'azienda o all'entità di cui stai richiedendo i dati e all'ambiente che stai chiamando.
• Controlla la disponibilità dell'endpoint. Verifica nella documentazione per sviluppatori che l'endpoint supporti il tuo metodo di autenticazione e il tuo caso d'uso.

Se questi corrispondono ma l'accesso è ancora negato, contatta il supporto per verificare l'accesso all'API dell'azienda. Indica se le stesse credenziali funzionano su altri endpoint.

L'endpoint o la risorsa richiesta non è stata trovata.

• Confronta l'URL di base, la versione dell'API e il percorso dell'endpoint con la documentazione per sviluppatori.
• Verifica che l'ID risorsa identifichi la risorsa che intendevi richiedere.
• Controlla che la risorsa appartenga all'azienda e all'ambiente associati alle credenziali. Non mescolare ID di staging e di produzione.

Una risorsa può restituire un errore 404 anche se esiste in Pleo, nel caso in cui appartenga a un'altra azienda o ambiente.

La richiesta è in conflitto con un'operazione o uno stato esistente.

• Leggi la risposta di errore e verifica se la stessa operazione è già stata inviata. Rivedi la risposta precedente o l'operazione risultante prima di inviarla di nuovo.
• Segui le indicazioni sull'idempotenza e la gestione dei conflitti dell'endpoint nella documentazione per sviluppatori.

La tua integrazione sta inviando richieste troppo frequentemente.

• Controlla le intestazioni della risposta per indicazioni su nuovi tentativi o limiti di velocità.
• Riduci la frequenza delle richieste ed evita di riprovare immediatamente in un ciclo stretto.
• Usa il backoff esponenziale, seguendo le indicazioni sui nuovi tentativi dell'endpoint.

Se il problema persiste con un volume di richieste basso, includi la frequenza delle richieste e il comportamento dei nuovi tentativi quando contatti il supporto.

Si è verificato un errore lato server. Raccogli la risposta di errore e i dettagli della richiesta elencati nella sezione "Hai ancora bisogno di aiuto?" e contatta il supporto. Indica se si è verificato una sola volta o si ripete.

Se gli eventi webhook non raggiungono la tua integrazione o non vengono elaborati dalla stessa:

• Verifica la raggiungibilità. Il tuo endpoint di ricezione deve essere pubblicamente accessibile tramite HTTPS e non deve bloccare le richieste provenienti da Pleo.
• Controlla i log di consegna. Cerca il tentativo di consegna, lo stato della risposta e il tempo di risposta. Restituisci una risposta 2xx tempestivamente, seguendo i requisiti della documentazione webhook.
• Verifica la firma. Usa il corpo della richiesta nel formato richiesto dalla documentazione webhook, incluso il corpo grezzo dove specificato.
• Gestisci le consegne duplicate in modo sicuro. Deduplicale usando l'identificatore di evento o webhook specificato nella documentazione.

Dopo aver apportato una modifica, controlla una consegna successiva. Se continua a non riuscire, includi l'ID abbonamento, l'ID evento o webhook, il timestamp di consegna, lo stato della risposta dell'endpoint e i log sanitizzati quando contatti il supporto.