Troubleshooting

A short list of issues that come up most often, and what to check first.

Device not responding

Open the Speakers or Routine Triggers page in the Voice Monkey console and click Test on the device. This proves the Voice Monkey → Alexa side end-to-end without involving any Alexa Routine.
If the test works but your real Routine doesn’t, open the Alexa app and run the Routine manually — does it work on its own?
If the Routine has multiple actions, test each one in isolation to find the broken step.

”The Test button works but my Alexa Routine doesn’t fire”

Voice Monkey’s side is working; the Alexa Routine is the problem.

Check the Routine isn’t disabled in the Alexa app.
Confirm the Routine is wired to the right event — Alexa Voice Monkey v3 → VM Speakers (or VM Routines) → the event name matching the device you’re triggering.
For Speakers, confirm the From Echo is the one you actually want to hear the announcement on.
Re-create the Routine if Amazon’s app has got itself into a bad state (more common than you’d think).

I don’t see “Alexa Voice Monkey v3” in the Alexa app

Voice Monkey only registers the smart-home device with Alexa once you’ve created your first Speaker or Routine Trigger.

If you haven’t created any devices yet, add one.
If you have, give the Alexa app a minute and pull-to-refresh the device list (the device appears via Alexa’s proactive discovery, which can take a few seconds).
Make sure you’re signed into the Alexa app with the same Amazon account you used to enable the Voice Monkey skill.

Announcement is cut short

Break long TTS into shorter sentences.
Shorten media (audio/video) clips.
Check the Echo’s volume isn’t muted by another Routine earlier in the sequence.

Flow started but nothing happened

Check the Flow’s Activity Log for the specific run — every node’s output is captured there.
Confirm the Flow is Enabled on the Flows list (disabled flows return FLOW_DISABLED from the API and are skipped by schedules and webhooks).
Verify each node’s target device still exists on your account.
For Scheduled Flows, confirm your plan still includes scheduling (Hobby or Ultimate).

Webhook isn’t firing

Hit the webhook URL with curl — confirm it’s the exact URL from the webhook’s edit page.
Open the URL in a browser. Voice Monkey serves a friendly help page on GET, so a 404 means the URL is malformed (typo, missing token, etc.).
On the webhook’s edit page, hit Refresh in the Recent Payload panel — confirms the webhook is receiving requests, even if the actions don’t fire.
If your action references payload values via {WEBHOOK.<slug>.<key>}, the slug is shown live under the Name field. Check it matches what your action uses.

API returns 401 Unauthorized

Token mismatch — check you’re using the latest token from app.voicemonkey.io/tokens.
Confirm you’re hitting the v3 host: https://api-v3.voicemonkey.io. The legacy api-v2 host is deprecated and no longer documented.
If you just rotated your token, the old one immediately stops working.

API returns 429 Too Many Requests

The body tells you which throttle tripped:

{"error":"THROTTLED","lockoutUntil":"<ISO>"} — per-user safety lockout. Back off until the timestamp in lockoutUntil before retrying. If you’re seeing this regularly, batch or deduplicate calls client-side, or spread bursts across a longer window.
{"error":"MONTHLY_QUOTA_EXCEEDED","periodEnd":"<ISO>"} — you’ve used your plan’s monthly request budget (Free 200, Hobby 15,000, Ultimate unlimited). Wait until the period end or upgrade your plan.

Last resort: disable and re-enable the skill

If you’ve ruled out the obvious causes and something still isn’t working — devices that worked yesterday no longer respond, the Alexa app doesn’t see Alexa Voice Monkey v3, account-link errors etc. — the nuclear option is to disable and re-enable the Voice Monkey skill in the Alexa app. This forces Alexa to refresh its access tokens and re-run device discovery, which fixes a surprising number of Alexa-side glitches.

In the Alexa app: More → Skills & Games → find Voice Monkey → Disable Skill.
Re-enable it from the same page (or from your country’s Voice Monkey skill listing — see Enable the skill for direct links).
Sign in with the same Amazon account when prompted to re-link.

Your Voice Monkey console data (devices, flows, variables, webhooks, tokens) is unaffected — you don’t have to recreate anything. Give the Alexa app a minute after re-enabling and try again.