Errori comuni

Sintomo. Tutte le chiamate inbound restituiscono 401 con codice API_KEY_EXPIRED. Il problema compare improvvisamente, senza modifiche al codice.

Causa. La chiave ha superato la data di scadenza impostata alla creazione.

Verifica.

curl -sS "$BP_API_BASE_URL/identity/v1/me" \
  -H "Authorization: Bearer $BP_API_KEY" | jq '.error.code, .data.expiresAt'

Soluzione. Crea una nuova chiave con gli stessi scope, distribuiscila nel gestore di segreti, riavvia i consumatori e revoca la vecchia. Procedura completa in Autenticazione.

Prevenzione. Attiva la notifica di scadenza a 30 giorni e pianifica la rotazione in calendario.

Sintomo. Alcune chiamate funzionano, altre restituiscono 403 con INSUFFICIENT_SCOPE. Tipicamente le letture passano e le scritture falliscono.

Causa. Alla chiave è stato assegnato solo lo scope di lettura.

Verifica.

curl -sS "$BP_API_BASE_URL/identity/v1/me" \
  -H "Authorization: Bearer $BP_API_KEY" | jq '.data.scopes'

Confronta l'elenco con lo scope indicato nel campo errors della risposta di errore.

Soluzione.

Prevenzione. Documenta gli scope necessari nel README dell'automazione e verificali nello smoke test di rilascio.

Sintomo. Il tuo endpoint risponde 401 a ogni consegna. Nei log consegne tutte le consegne risultano fallite con lo stesso codice.

Causa. Segreto errato, stringa firmata costruita male, corpo non grezzo, oppure rotazione del segreto non completata.

Verifica. Scarica il corpo grezzo dai log consegne e ricalcola la firma offline:

TIMESTAMP="1767225600"
openssl dgst -sha256 -hmac "$BP_WEBHOOK_SECRET" -r \
  <(printf '%s.' "$TIMESTAMP"; cat corpo.json) | cut -d' ' -f1

Confronta il risultato con il valore v1 dell'header registrato.

Soluzione. Se il valore calcolato coincide, il bug è nel tuo codice: probabilmente stai ri-serializzando il JSON. Se non coincide, il segreto è sbagliato: ricopialo dalla Console. Dettagli in Firma HMAC.

Prevenzione. Test unitario sulla verifica della firma con un caso noto, eseguito in CI.

Sintomo. Rifiuti con 400 e motivo timestamp-fuori-tolleranza, spesso intermittenti o concentrati sotto carico.

Causa. Orologio del server non sincronizzato, oppure verifica eseguita in un worker asincrono che elabora la richiesta molti minuti dopo la ricezione.

Verifica.

# Scarto rispetto all ora di rete
timedatectl status
chronyc tracking | grep "System time"

# Confronto con un server pubblico
curl -sSI https://api.blupantheon.com | grep -i '^date:'
date -u

Soluzione. Attiva NTP. Sposta la verifica della firma all'ingresso della richiesta HTTP, prima di qualunque coda interna.

Prevenzione. Allarme se lo scarto dell'orologio supera i 30 secondi.

Sintomo. Log consegne con motivo connessione rifiutata o host non risolto. Nessuna traccia nei log del tuo server.

Causa. DNS non propagato, firewall che blocca il traffico in ingresso, servizio fermo, oppure endpoint pubblicato solo in rete interna.

Verifica.

# Risoluzione DNS
dig +short automation.acme.it

# Raggiungibilità della porta 443 dall esterno
nc -zv automation.acme.it 443

# Richiesta di prova da una rete esterna alla tua
curl -sS -o /dev/null -w "%{http_code}\n" \
  -X POST "https://automation.acme.it/webhooks/blupantheon" \
  -H "Content-Type: application/json" --data-raw '{}'

Esegui i comandi da una rete esterna alla tua: dall'interno funzionerebbe comunque.

Soluzione. Pubblica l'endpoint, apri la porta 443 in ingresso, verifica che il reverse proxy inoltri correttamente il percorso.

Prevenzione. Monitor sintetico esterno che interroga /health ogni minuto.

Sintomo. Log consegne con motivo TLS non valido o certificato scaduto. Il browser mostra un avviso di sicurezza sull'endpoint.

Causa. Certificato scaduto, catena intermedia incompleta, hostname non corrispondente, oppure certificato autofirmato.

Verifica.

openssl s_client -connect automation.acme.it:443 \
  -servername automation.acme.it </dev/null 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates

# Verifica della catena completa
curl -sS -o /dev/null -w "%{ssl_verify_result}\n" https://automation.acme.it/

Un valore diverso da 0 in ssl_verify_result indica un problema di verifica.

Soluzione. Rinnova il certificato e installa la catena completa, non solo il certificato foglia. Molti server dimenticano gli intermedi: il browser li recupera automaticamente, i client HTTP no.

Prevenzione. Rinnovo automatico e allarme a 30 giorni dalla scadenza.

Sintomo. Log consegne con motivo timeout e tempo di risposta pari a 10000 ms. Il tuo sistema riceve e talvolta elabora più volte lo stesso evento.

Causa. L'elaborazione del gestionale avviene dentro la richiesta HTTP del webhook.

Verifica.

curl -sS -o /dev/null \
  -w "totale %{time_total}s (connessione %{time_connect}s, TLS %{time_appconnect}s)\n" \
  -X POST "https://automation.acme.it/webhooks/blupantheon" \
  -H "Content-Type: application/json" --data-raw '{}'

Soluzione. Separa ricezione ed elaborazione: verifica la firma, accoda, rispondi 202. Elabora in un worker separato. Pattern descritto in Modello di integrazione.

Prevenzione. Allarme sul p95 del tempo di risposta oltre 500 ms.

Sintomo. Log consegne con codice 301, 302, 307 o 308 e stato fallito. L'endpoint funziona perfettamente da browser.

Causa. Regola di riscrittura del reverse proxy: da HTTP a HTTPS, da dominio senza www a dominio con www, oppure aggiunta della barra finale al percorso.

Verifica.

curl -sS -o /dev/null -w "%{http_code} -> %{redirect_url}\n" \
  -X POST "https://automation.acme.it/webhooks/blupantheon" \
  -H "Content-Type: application/json" --data-raw '{}'

Se redirect_url non è vuoto, hai trovato la causa.

Soluzione. Registra in Console l'URL finale, quello che non produce redirect. Se la riscrittura riguarda la barra finale, includila o rimuovila coerentemente.

Prevenzione. Nel test di registrazione dell'endpoint verifica sempre che il codice sia 2xx diretto, senza salti.

Sintomo. Il tuo endpoint risponde 413. Accade solo su alcuni eventi, tipicamente sessioni lunghe o documenti con molti campi estratti.

Causa. Limite di dimensione del corpo configurato troppo basso nel server o nel proxy.

Verifica. Controlla la dimensione del corpo nei log consegne e confrontala con il limite configurato.

# NGINX
grep -r "client_max_body_size" /etc/nginx/

# Express
grep -rn "limit:" server.js

Soluzione. Imposta un limite di almeno 2 MB:

location /webhooks/blupantheon {
    client_max_body_size 2m;
    proxy_pass http://127.0.0.1:3000;
    proxy_request_buffering off;
}

app.post('/webhooks/blupantheon', express.raw({ type: 'application/json', limit: '2mb' }), handler);

Prevenzione. Testa con un payload realistico di sessione lunga, non con un evento di prova minimale.

Sintomo. Nel gestionale compaiono ordini, clienti o ticket duplicati. Il problema si concentra nei periodi in cui il sistema era lento.

Causa. Nessuna deduplica su X-BP-Delivery e nessun Idempotency-Key sulle scritture. Ogni ritentativo di consegna riesegue l'operazione.

Verifica. Cerca nel gestionale record con lo stesso riferimento creati a distanza di 1, 5 o 30 minuti: coincidono con la sequenza di ritentativi.

SELECT RIFEST, COUNT(*) AS occorrenze, MIN(created_at), MAX(created_at)
FROM ordini
WHERE created_at > NOW() - INTERVAL 7 DAY
GROUP BY RIFEST
HAVING COUNT(*) > 1;

Soluzione. Implementa la deduplica a due livelli descritta in Webhook: tabella con delivery_id come chiave primaria e controllo aggiuntivo sul campo id dell'evento. Aggiungi Idempotency-Key su tutte le scritture inbound.

Prevenzione. Test di rilascio che invia due volte la stessa consegna e verifica che venga creato un solo record.

Sintomo. Risposte 429 con RATE_LIMIT_EXCEEDED, tipicamente durante import massivi o riallineamenti.

Causa. Troppe richieste in parallelo, oppure polling con intervallo troppo breve.

Verifica.

curl -sS -D - -o /dev/null \
  "$BP_API_BASE_URL/identity/v1/clients?limit=1" \
  -H "Authorization: Bearer $BP_API_KEY" \
  | grep -i "x-ratelimit"

Soluzione.

1. Rispetta sempre Retry-After: è il valore corretto, non usare attese fisse.
2. Riduci il parallelismo a un massimo di 5 richieste concorrenti.
3. Aumenta limit nelle query paginate per ridurre il numero di chiamate.
4. Sostituisci il polling frequente con i webhook.
5. Metti in cache locale i dati che cambiano raramente, come le tabelle dei servizi.

Prevenzione. Allarme quando X-RateLimit-Remaining scende sotto il 10% del limite.

Sintomo. 403 con codice IP_NOT_ALLOWED. La stessa chiave funziona da una postazione e non da un'altra, oppure smette di funzionare dopo una migrazione infrastrutturale.

Causa. Sulla chiave API è configurata una restrizione per indirizzo IP e l'automazione esce con un IP diverso, ad esempio dopo un cambio di NAT gateway o uno scale-out.

Verifica.

# IP pubblico di uscita del server dell automazione
curl -sS https://api.ipify.org
echo

# Confronto con la allowlist configurata
curl -sS "$BP_API_BASE_URL/identity/v1/me" \
  -H "Authorization: Bearer $BP_API_KEY" | jq '.error'

Soluzione.

Prevenzione. Documenta gli IP di uscita nel registro dell'integrazione e aggiorna la allowlist come parte di ogni migrazione infrastrutturale.