Passa al contenuto principale

Problemi comuni

Un elenco aggiornato dei problemi di cui ci parlano più spesso, con le relative soluzioni. Se incontri qualcosa che non è trattato qui, contattaci e ti aiuteremo — aggiungendolo inoltre a questa pagina.

401 Unauthorized​

Sintomo. Ogni richiesta restituisce 401 con {"error":{"code":"invalid_api_key"}}.

Causa. Di solito uno dei seguenti motivi:

  • Nell'header Authorization manca il prefisso Bearer .
  • La chiave è per un ambiente diverso rispetto all'URL che stai chiamando (chiave sandbox, URL di produzione, o viceversa).
  • La chiave è stata ruotata o revocata dalla dashboard.

Soluzione. Verifica la chiave in locale:

echo "Key prefix: ${SNAPBYTE_API_KEY:0:7}"
# sk_live_... = production, sk_test_... = sandbox

Se il prefisso non corrisponde all'URL che stai chiamando, sostituisci uno dei due. Se la chiave è corretta, ruotala nella dashboard e aggiorna il tuo ambiente.

429 Too Many Requests​

Sintomo. Le richieste iniziano a fallire con 429 sotto carico.

Causa. Hai superato il limite di frequenza per la tua chiave. Ogni risposta include gli header x-snapbyte-ratelimit / x-snapbyte-remaining / x-snapbyte-reset — controlla remaining per vedere quanto sei vicino al limite.

Soluzione. Attendi fino al timestamp reset. L'SDK lo fa già automaticamente; se stai chiamando l'API direttamente, implementa un backoff esponenziale con jitter.

Job falliti​

Sintomo. Un job termina nello stato failed con un error strutturato.

Causa. Dipende dal valore di error.code:

error.codeSignificato
invalid_payloadIl payload del job non corrispondeva allo schema.
dependency_failedUn servizio a monte chiamato da Snapbyte ha restituito un errore.
timeoutIl job ha superato il tempo di esecuzione massimo.

Soluzione. Registra job.error per intero quando gestisci un job fallito — i campi message e param individuano quasi sempre con precisione il problema.

Mancata corrispondenza della firma del webhook​

Sintomo. verifyWebhook genera InvalidSignature.

Causa. Quasi sempre uno dei seguenti motivi:

  • Un middleware (ad esempio express.json()) ha riserializzato il corpo della richiesta prima che tu calcolassi la firma — Snapbyte firma i byte grezzi.
  • Viene passato il segreto dell'endpoint errato (ad esempio il segreto sandbox per un webhook di produzione).

Soluzione. Cattura il corpo grezzo della richiesta prima di qualsiasi analisi JSON:

app.use('/webhooks/snapbyte', express.raw({type: 'application/json'}));

Poi verifica rispetto a req.body (un Buffer) prima di analizzarlo come JSON.

Sviluppo locale: EADDRINUSE su npm run start​

Sintomo. Docusaurus si rifiuta di avviarsi, segnalando che la porta 3000 è in uso.

Soluzione.

npm run start -- --port 3001

Oppure termina ciò che sta occupando la porta:

lsof -ti tcp:3000 | xargs kill