Problemes habituals
Una llista contínua dels problemes que ens consulten més sovint, amb les seues solucions. Si trobes alguna cosa que no està coberta ací, posa't en contacte i t'ajudarem, i l'afegirem a esta pàgina.
401 No autoritzat
Símptoma. Cada sol·licitud torna 401 amb
{"error":{"code":"invalid_api_key"}}.
Causa. Normalment una d'estes:
- A la capçalera
Authorizationli falta el prefixBearer. - La clau és d'un entorn diferent de l'URL que estàs cridant (clau de sandbox, URL de producció, o a l'inrevés).
- La clau es va rotar o revocar des del tauler.
Solució. Comprova la clau localment:
echo "Key prefix: ${SNAPBYTE_API_KEY:0:7}"
# sk_live_... = production, sk_test_... = sandbox
Si el prefix no coincidix amb l'URL que estàs cridant, canvia'n un. Si la clau és correcta, rota-la en el tauler i actualitza el teu entorn.
429 Massa sol·licituds
Símptoma. Les sol·licituds comencen a fallar amb 429 sota càrrega.
Causa. Has superat el límit de velocitat de la teua clau. Cada resposta inclou
les capçaleres x-snapbyte-ratelimit / x-snapbyte-remaining /
x-snapbyte-reset: comprova remaining per a veure com de prop estàs.
Solució. Espera fins a la marca de temps de reset. L'SDK ja ho fa
automàticament; si crides l'API directament, implementa una espera exponencial amb
variació aleatòria (jitter).
Treballs fallits
Símptoma. Un treball acaba en l'estat failed amb un error estructurat.
Causa. Depèn del error.code:
error.code | Significat |
|---|---|
invalid_payload | El payload del treball no coincidia amb l'esquema. |
dependency_failed | Un servei extern que Snapbyte ha cridat ha tornat un error. |
timeout | El treball ha superat el temps d'execució màxim. |
Solució. Registra job.error complet quan gestiones un treball fallit: els
camps message i param quasi sempre assenyalen el problema.
Discordança de la signatura del webhook
Símptoma. verifyWebhook llança InvalidSignature.
Causa. Quasi sempre una d'estes:
- Un middleware (per exemple,
express.json()) ha tornat a serialitzar el cos de la sol·licitud abans que en calcules la signatura: Snapbyte signa els bytes en brut. - S'està passant el secret d'endpoint incorrecte (per exemple, el secret de sandbox per a un webhook de producció).
Solució. Captura el cos en brut de la sol·licitud abans de qualsevol anàlisi de JSON:
app.use('/webhooks/snapbyte', express.raw({type: 'application/json'}));
Després verifica contra req.body (un Buffer) abans d'analitzar-lo com a JSON.
Desenvolupament local: EADDRINUSE en npm run start
Símptoma. Docusaurus es nega a iniciar-se i es queixa que el port 3000 està en ús.
Solució.
npm run start -- --port 3001
O bé mata el que estiga ocupant el port:
lsof -ti tcp:3000 | xargs kill