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
Authorizationmanca il prefissoBearer. - 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.code | Significato |
|---|---|
invalid_payload | Il payload del job non corrispondeva allo schema. |
dependency_failed | Un servizio a monte chiamato da Snapbyte ha restituito un errore. |
timeout | Il 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