Skip to main content

Common issues

A running list of the issues we hear about most often, with fixes. If you hit something that isn't covered here, get in touch and we'll help — and add it to this page.

401 Unauthorized​

Symptom. Every request returns 401 with {"error":{"code":"invalid_api_key"}}.

Cause. Usually one of:

  • The Authorization header is missing the Bearer prefix.
  • The key is for a different environment than the URL you're hitting (sandbox key, production URL, or vice versa).
  • The key was rotated or revoked from the dashboard.

Fix. Confirm the key locally:

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

If the prefix doesn't match the URL you're calling, swap one of them. If the key is correct, rotate it in the dashboard and update your environment.

429 Too Many Requests​

Symptom. Requests start failing with 429 under load.

Cause. You're over the rate limit for your key. Every response includes x-snapbyte-ratelimit / x-snapbyte-remaining / x-snapbyte-reset headers — check remaining to see how close you are.

Fix. Back off until the reset timestamp. The SDK already does this automatically; if you're calling the API directly, implement an exponential backoff with jitter.

Failed jobs​

Symptom. A job ends in the failed state with a structured error.

Cause. Depends on the error.code:

error.codeMeaning
invalid_payloadThe job's payload didn't match the schema.
dependency_failedAn upstream service Snapbyte called returned an error.
timeoutThe job exceeded the maximum runtime.

Fix. Log job.error in full when handling a failed job — the message and param fields almost always pinpoint the issue.

Webhook signature mismatch​

Symptom. verifyWebhook throws InvalidSignature.

Cause. Almost always one of:

  • A middleware (e.g. express.json()) re-serialized the request body before you computed the signature — Snapbyte signs the raw bytes.
  • The wrong endpoint secret is being passed in (e.g. sandbox secret for a production webhook).

Fix. Capture the raw body on the request before any JSON parsing:

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

Then verify against req.body (a Buffer) before parsing it as JSON.

Local dev: EADDRINUSE on npm run start​

Symptom. Docusaurus refuses to start, complaining port 3000 is in use.

Fix.

npm run start -- --port 3001

Or kill whatever is holding the port:

lsof -ti tcp:3000 | xargs kill