Vés al contingut principal

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 Authorization li falta el prefix Bearer .
  • 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.codeSignificat
invalid_payloadEl payload del treball no coincidia amb l'esquema.
dependency_failedUn servei extern que Snapbyte va cridar ha retornat un error.
timeoutEl 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