Gestire gli errori delle API: dagli errori 401 e 422 a un'autocorrezione limitata

Quando una richiesta fallisce, la prima domanda per un client non è «quante altre volte possiamo riprovare?» ma «è stata eseguita, e cosa deve cambiare perché un nuovo tentativo abbia senso?». Chiavi mancanti, nomi di piattaforma errati, parametri non supportati e connessioni interrotte durante lo streaming della risposta possono finire tutti nello stesso blocco catch. Gestire allo stesso modo tutti i nuovi tentativi trasforma input correggibili in errori ripetuti e può persino duplicare attività già create.

Questo articolo usa un'interfaccia REST di EveryInfra come esempio per illustrare la classificazione degli errori per livelli, il controllo del catalogo e pratiche di autocorrezione limitata. Il motore decisionale di esempio restituisce solo suggerimenti sul passo successivo: non invia richieste, non cambia credenziali e non amplia mai automaticamente l'ambito dei dati. Codice sorgente attuale, verifiche pubbliche gratuite e campioni storici di produzione vengono usati separatamente, per non dedurre da una singola risposta 400 tutto il comportamento degli errori nelle richieste autenticate.

Conserva il tentativo prima di analizzare l'errore

Prima della chiamata, genera un ID dell'operazione di business per correlare più tentativi con lo stesso intento. Per ogni tentativo salva orari di inizio e fine, versione della richiesta, funzionalità target, codice di stato HTTP e gli ID di richiesta del servizio disponibili. Gli ID di business non sono chiavi di idempotenza del server: se il servizio non ne dichiara il supporto, non puoi presumere che reinviare con lo stesso ID attivi la deduplicazione.

Il corpo della risposta può essere HTML, testo semplice, vuoto o JSON non analizzabile. Controlla Content-Type e stato prima di provare ad analizzare l'errore. Se il parsing fallisce, conserva un riepilogo diagnostico minimo senza inserire le pagine di errore grezze direttamente nei prompt degli utenti né passarle agli agenti come istruzioni. Per impostazione predefinita, i log omettono chiavi, URL firmati completi, corpi grezzi e altri dati personali non necessari.

L'attuale envelope pubblico degli errori di EveryInfra contiene error.code, error.message ed error.request_id. Organizza la gestione attorno ai codici e agli stati HTTP, trattando i messaggi come testo destinato alle persone. Non contare sul fatto che i messaggi in inglese restino invariati e non usare il primo URL trovato in una stringa per navigare automaticamente portandoti dietro le credenziali.

Per le allowlist diagnostiche puoi fare riferimento all'OWASP Logging Cheat Sheet: usa identificatori di interazione per correlare gli eventi e oscura token, valori di sessione e informazioni sensibili. I log degli errori devono fornire contesto sufficiente a individuare un tentativo senza diventare una fonte alternativa di credenziali o una copia dei dati dei clienti.

401 e 403: gestisci separatamente autenticazione e autorizzazione

HTTP 401 indica l'assenza di credenziali di autenticazione valide; 403 indica che il server rifiuta la richiesta. Gli stati del protocollo forniscono il significato generale, mentre le cause specifiche dipendono dai codici di errore del prodotto. Nell'implementazione attuale di EveryInfra, chiavi mancanti, non valide o scadute sono problemi di autenticazione, mentre i limiti su prodotti, singole funzionalità e IP di origine sono problemi di autorizzazione.

Verifica innanzitutto che la richiesta abbia raggiunto il servizio corretto, che gli header Authorization rispettino i requisiti del servizio e che il processo in esecuzione legga l'ambiente previsto. Controlla l'esistenza delle variabili e i flag di configurazione senza stampare i segreti. Una sessione della console aperta nel browser non prova che il processo lato server abbia ottenuto la chiave API corretta.

In caso di errori di autenticazione consecutivi, sospendi le attività interessate e avvisa il responsabile; per ripristinare il servizio non passare da una chiave all'altra, non cambiare account e non disattivare i limiti dei permessi. Il rinnovo automatico vale solo per i flussi autorizzati esplicitamente e supportati dal prodotto; le chiavi API a lunga durata non sono token che si rinnovano da soli.

Nome della funzionalità errato: leggi prima i candidati, poi verifica il target

Un errore pubblico senza chiave si può osservare così. Qui viene passato di proposito l'identificatore obsoleto google_maps solo per leggere il catalogo, senza raccogliere recensioni di luoghi:

curl --silent --show-error --include --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=google_maps'

Il risultato del 2026-09-04 alle 20:46 (ora di Pechino) è HTTP 400, con error.code pari a unknown_capability e un messaggio che include google_maps_reviews insieme a un altro candidato simile. Le funzionalità sconosciute non si possono mappare sempre su 404, e l'attività originale non va cambiata automaticamente solo perché un candidato è il primo della lista.

Se l'attività originale riguarda proprio le recensioni dei luoghi, verifica che google_maps_reviews fornisca reviews, quale struttura di URL richieda e se il suo output soddisfi i requisiti originali. Gli algoritmi di corrispondenza dei candidati risolvono solo le somiglianze tra nomi e non capiscono l'intento di business; gli app store e le recensioni dei luoghi non sono fonti di dati intercambiabili.

422: correggi gli input per allinearli ai parametri attuali

422 indica in genere che il contenuto della richiesta è stato compreso, ma le istruzioni che contiene non possono essere elaborate. Le applicazioni dovrebbero distinguere ulteriormente tra campi mancanti, campi sconosciuti, enumerazioni non valide e limiti di dimensione, perché la correzione è diversa: un URL mancante richiede un target reale, un'opzione di ordinamento sconosciuta richiede la validazione dei parametri, un input troppo grande richiede opzioni di suddivisione confermate invece di scartare in silenzio metà del materiale di partenza.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=douyin' \
  | jq '[.capabilities[] | {
      action, required_params, optional_params, param_meanings, max_limit
    }]'

L'implementazione attuale restituisce unknown_param per i parametri sconosciuti e invalid_value per le enumerazioni non supportate, accompagnati da suggerimenti utili. Tuttavia un parametro con lo stesso nome può comportarsi diversamente da un'azione all'altra, quindi una tabella globale dei parametri non sostituisce il riferimento dei parametri di ciascuna azione. required_params, optional_params e i valori ammessi vanno valutati insieme, e i limiti generici degli elenchi non sono impegni sulla paginazione.

Dopo le correzioni genera una nuova versione della richiesta, conservando l'errore originale e il motivo della modifica. Applica le mappature automaticamente solo quando l'intento originale resta esplicitamente invariato; servono decisioni umane in caso di più candidati, target reali mancanti, intervalli temporali ampliati o cambi di modello. Riempire i campi mancanti con ipotesi del modello non è un'autocorrezione sicura.

402 e 429: non scambiare i problemi di quota per limiti di frequenza delle richieste

Attualmente EveryInfra usa 402 quota_exhausted per indicare una quota insufficiente: è una convenzione specifica del prodotto, non un significato di business del codice 402 valido per tutti i servizi. I problemi di quota richiedono l'intervento del titolare dell'account; ridurre le richieste simultanee non aumenta automaticamente il saldo, e i client non devono effettuare ricariche automatiche né migrare le credenziali.

429 è un segnale di limite di frequenza delle richieste. Se la risposta include un header Retry-After valido, segui le sue indicazioni; la sua assenza non implica nuovi tentativi immediati e ravvicinati, né autorizza a inventare tempi di ripristino del servizio. Intervalli tra i tentativi, jitter, numero massimo di tentativi e scadenze devono essere definiti esplicitamente dalle policy dell'applicazione.

Le strategie di limitazione della frequenza devono coprire tutti i processi worker che condividono una quota. Se un solo worker rallenta mentre gli altri continuano a inviare richieste, la congestione resta. Queste indicazioni riguardano lo scheduling dell'applicazione e non implicano che l'API coordini per tuo conto più processi client.

Errori 5xx, disconnessioni e task inviati: verifica prima lo stato di esecuzione

Un errore 5xx non può essere interpretato semplicemente come «non è successo nulla». Il servizio potrebbe aver accettato la richiesta, generato risultati parziali o completato fasi di addebito senza che il client ricevesse una risposta completa. In assenza di garanzie esplicite di idempotenza o di prove dell'esecuzione, registra il risultato come sconosciuto e verificalo tramite gli identificatori della richiesta invece di reinviare automaticamente una POST.

Quando sono disponibili un job_id o un endpoint di interrogazione fornito dal servizio, interroga prima il task originale. In esecuzione, in fase di chiusura, riuscito, non riuscito ed errore dell'interrogazione vanno trattati come stati distinti; un 404 nell'interrogazione può dipendere da problemi di identità o di ambito e non deve portare alla creazione di un task alternativo. Verifica che l'interrogazione usi l'identità corrispondente alla richiesta originale.

Anche dopo un HTTP 200 il contenuto di business va controllato. MCP aggiunge i livelli di errore JSON-RPC e degli strumenti, quindi non basta una strategia pensata solo per REST. Insiemi vuoti, risultati parziali e risposte anomale mantengono i propri stati e non vanno marcati in blocco come successi; gli addebiti finali non si possono ricavare solo dallo stato lato client.

Il pattern Retry di Microsoft ricorda un punto chiave: ripeti solo i guasti recuperabili, tenendo conto dell'idempotenza dell'operazione e dei livelli sovrapposti che eseguono nuovi tentativi. Se SDK, code e livello di business riprovano ciascuno in autonomia, i tentativi totali possono superare il budget; a decidere dovrebbe essere un solo livello che conosce il contesto completo, invece di «riprovare» ovunque per impostazione predefinita.

Un motore decisionale che instrada senza eseguire nuovi tentativi

Quello che segue è un esempio offline a livello applicativo, non un SDK di EveryInfra. Gli input devono provenire da record dei tentativi REST già sottoposti al parsing del protocollo; retry_after_policy_check va impostato in base ad accordi reali sull'interfaccia o a prove esplicite di mancata esecuzione, e non deve essere attivato arbitrariamente da modelli o dal testo degli errori. attempts tiene traccia del numero di tentativi precedenti.

function nextStep({status, hasJob = false, replaySafe = false,
                   attempts = 1, maxAttempts = 3}) {
  if (status !== null && (!Number.isInteger(status) || status < 100 || status > 599)) {
    throw new Error("invalid HTTP status");
  }
  if (typeof hasJob !== "boolean" || typeof replaySafe !== "boolean"
      || !Number.isSafeInteger(attempts) || attempts < 1
      || !Number.isSafeInteger(maxAttempts) || maxAttempts < 1) {
    throw new Error("invalid decision inputs");
  }
  if (status === 401 || status === 403) return "authorization_review";
  if (status === 402) return "account_review";
  if (hasJob) return "inspect_existing_job";
  if (status === 400 || status === 422) return "revise_request";
  if (status === 429 || status === null || (status >= 500 && status <= 599)) {
    return replaySafe && attempts < maxAttempts
      ? "retry_after_policy_check"
      : "inspect_attempt";
  }
  if (status >= 200 && status < 300) return "validate_delivery";
  return "manual_review";
}

// synthetic attempt; contains no network calls.
console.log(nextStep({status: 503}));
console.log(nextStep({status: 429, replaySafe: true, attempts: 3}));
console.log(nextStep({status: 202, hasJob: true}));

I tre output richiedono, rispettivamente, di controllare il tentativo corrente, di controllare i tentativi dopo l'esaurimento del budget e di interrogare il task originale. retry_after_policy_check non è un comando per riprovare subito; i livelli esterni devono verificare anche i tempi di attesa, i limiti di frequenza globali e gli ambiti operativi consentiti dall'utente. I nuovi tentativi costruiti dopo aver modificato i parametri rientrano nel budget complessivo di business e non devono generare cicli infiniti azzerando i contatori.

Verificare che i sistemi si fermino è importante quanto verificarne il ripristino

• Autenticazione non valida: non accede a credenziali alternative e non avvia nuovi tentativi di business.
• Funzionalità candidate ambigue: mantiene i target originali, richiede una verifica e impedisce il passaggio automatico a un altro prodotto.
• Richieste accettate con risposta interrotta: conserva i tentativi e i task originali senza crearne duplicati.
• Errore persistente dopo la correzione dei parametri: registra le nuove versioni rispettando il budget complessivo dei tentativi.
• Errori non JSON, ID richiesta mancanti, codici sconosciuti: passa a una gestione prudente senza andare in crash né inventare un successo.
• Dati disponibili restituiti ma obiettivi di business non raggiunti: conserva lo stato di consegna e i problemi da seguire, senza dichiarare unilateralmente il ripristino del saldo.

Mantieni un piccolo set di errori di esempio e rieseguilo quando aggiorni gli SDK, quando cambiano i parametri dell'API o quando modifichi la strategia di autenticazione. I test sul codice sorgente verificano le sequenze attese, ma i deployment in produzione richiedono prove limitate con input reali, con date registrate separatamente per ciascuna. Non sostituire l'accettazione di business autenticata di oggi con vecchi screenshot o con errori della directory gratuita.

Lo scopo dell'auto-riparazione sicura è fare in modo che i problemi chiaramente risolvibili richiedano meno spesso l'intervento umano, interrompendo tempestivamente l'esecuzione quando è davvero necessario un giudizio umano. Finché ogni passaggio chiarisce dove si è verificato l'errore, cosa è cambiato, se l'esecuzione è avvenuta e perché il passaggio successivo è consentito, i messaggi di errore diventano veri strumenti di integrazione anziché inneschi per nuovi tentativi infiniti.