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
Authorizationle falta el prefijoBearer. - 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.code | Significado |
|---|---|
invalid_payload | El payload del trabajo no coincidió con el esquema. |
dependency_failed | Un servicio externo al que llamó Snapbyte devolvió un error. |
timeout | El 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