Problemes habituals
Una llista en evolució dels problemes que ens consulten més sovint, amb les seves solucions. Si us trobeu amb alguna cosa que no s'hi tracta, poseu-vos en contacte i us ajudarem —i ho afegirem a aquesta pàgina.
401 Unauthorized
Símptoma. Totes les sol·licituds retornen 401 amb
{"error":{"code":"invalid_api_key"}}.
Causa. Normalment una d'aquestes:
- A la capçalera
Authorizationli falta el prefixBearer. - La clau és d'un entorn diferent de l'URL que esteu utilitzant (clau de sandbox amb URL de producció, o a la inversa).
- La clau es va rotar o revocar des del tauler de control.
Solució. Confirmeu la clau localment:
echo "Key prefix: ${SNAPBYTE_API_KEY:0:7}"
# sk_live_... = production, sk_test_... = sandbox
Si el prefix no coincideix amb l'URL que esteu cridant, canvieu-ne un. Si la clau és correcta, roteu-la al tauler de control i actualitzeu el vostre entorn.
429 Too Many Requests
Símptoma. Les sol·licituds comencen a fallar amb 429 sota càrrega.
Causa. Heu superat el límit de freqüència de la vostra clau. Cada resposta
inclou les capçaleres x-snapbyte-ratelimit / x-snapbyte-remaining /
x-snapbyte-reset: comproveu remaining per veure com de prop esteu del límit.
Solució. Espereu fins a la marca de temps de reset. L'SDK ja ho fa
automàticament; si crideu l'API directament, implementeu un reintent amb
espera exponencial i variació aleatòria (jitter).
Treballs fallits
Símptoma. Un treball acaba en l'estat failed amb un error estructurat.
Causa. Depèn de l'error.code:
error.code | Significat |
|---|---|
invalid_payload | El payload del treball no coincidia amb l'esquema. |
dependency_failed | Un servei extern que Snapbyte va cridar ha retornat un error. |
timeout | El treball ha superat el temps d'execució màxim. |
Solució. Registreu job.error complet quan gestioneu un treball fallit: els
camps message i param gairebé sempre assenyalen el problema.
La signatura del webhook no coincideix
Símptoma. verifyWebhook llança InvalidSignature.
Causa. Gairebé sempre una d'aquestes:
- Un middleware (per exemple,
express.json()) ha tornat a serialitzar el cos de la sol·licitud abans que en calculéssiu la signatura: Snapbyte signa els bytes en cru. - S'està passant el secret de punt de connexió equivocat (per exemple, el secret de sandbox per a un webhook de producció).
Solució. Captureu el cos en cru de la sol·licitud abans de qualsevol anàlisi de JSON:
app.use('/webhooks/snapbyte', express.raw({type: 'application/json'}));
Després, verifiqueu-lo contra req.body (un Buffer) abans d'analitzar-lo com
a JSON.
Desenvolupament local: EADDRINUSE en npm run start
Símptoma. Docusaurus no s'inicia i es queixa que el port 3000 està en ús.
Solució.
npm run start -- --port 3001
O bé, finalitzeu el que estigui ocupant el port:
lsof -ti tcp:3000 | xargs kill