Salta al contingut principal

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