Saltar al contenido principal

Problemas comunes

Una lista actualizada de los problemas que nos consultan con más frecuencia, con sus soluciones. Si te encuentras con algo que no aparece aquí, ponte en contacto y te ayudaremos, además de añadirlo a esta página.

401 Unauthorized​

Síntoma. Cada solicitud devuelve 401 con {"error":{"code":"invalid_api_key"}}.

Causa. Normalmente, una de estas:

  • A la cabecera Authorization le falta el prefijo Bearer .
  • La clave es de un entorno distinto al de la URL a la que llamas (clave de sandbox con URL de producción, o viceversa).
  • La clave se rotó o se revocó desde el panel de control.

Solución. Confirma la clave localmente:

echo "Key prefix: ${SNAPBYTE_API_KEY:0:7}"
# sk_live_... = production, sk_test_... = sandbox

Si el prefijo no coincide con la URL a la que llamas, cambia uno de los dos. Si la clave es correcta, rótala en el panel de control y actualiza tu entorno.

429 Too Many Requests​

Síntoma. Las solicitudes empiezan a fallar con 429 bajo carga.

Causa. Has superado el límite de velocidad de tu clave. Cada respuesta incluye las cabeceras x-snapbyte-ratelimit / x-snapbyte-remaining / x-snapbyte-reset: revisa remaining para ver cómo de cerca estás.

Solución. Espera hasta la marca de tiempo de reset. El SDK ya lo hace automáticamente; si llamas a la API directamente, implementa un retroceso exponencial con variación aleatoria (jitter).

Trabajos fallidos​

Síntoma. Un trabajo termina en el estado failed con un error estructurado.

Causa. Depende del error.code:

error.codeSignificado
invalid_payloadEl payload del trabajo no coincidió con el esquema.
dependency_failedUn servicio externo al que llamó Snapbyte devolvió un error.
timeoutEl trabajo superó el tiempo máximo de ejecución.

Solución. Registra job.error por completo al gestionar un trabajo fallido: los campos message y param casi siempre señalan con precisión el problema.

El error de firma del webhook no coincide​

Síntoma. verifyWebhook lanza InvalidSignature.

Causa. Casi siempre, una de estas:

  • Un middleware (por ejemplo, express.json()) volvió a serializar el cuerpo de la solicitud antes de que calcularas la firma: Snapbyte firma los bytes sin procesar (raw).
  • Se está pasando el secreto de endpoint incorrecto (por ejemplo, el secreto de sandbox para un webhook de producción).

Solución. Captura el cuerpo sin procesar de la solicitud antes de cualquier análisis JSON:

app.use('/webhooks/snapbyte', express.raw({type: 'application/json'}));

Después, verifica con req.body (un Buffer) antes de analizarlo como JSON.

Desarrollo local: EADDRINUSE al ejecutar npm run start​

Síntoma. Docusaurus se niega a arrancar y avisa de que el puerto 3000 está en uso.

Solución.

npm run start -- --port 3001

O bien, finaliza lo que esté ocupando el puerto:

lsof -ti tcp:3000 | xargs kill