Updated August 26, 2026. This revision was checked against Amazon’s current support documentation and separates actual failures from normal device states and Alexa+ interface changes.
What to know before troubleshooting
- HTTP 299 was a symptom of a specific compatibility break, not a standard status code that identifies every current failure.
- Alexa Media Player is a community integration that mimics the Alexa app through an unofficial Amazon API.
- Treat HACS, Home Assistant, and the integration as a compatibility set, and read release notes before deleting the config entry.
Start with the least destructive check. Restarting is safe; a factory reset erases settings and should be the final step.
See the official support documentation as well. Menu labels can differ between original Alexa, Alexa+, and screen-based Echo devices.
For voice announcements and fallback options, see the Home Assistant voice switchboard.
Complete guide and step-by-step fixes
The “299 is not a valid HTTPStatus” message became widely visible when Amazon changed a response used by Alexa Media Player. Python’s standard HTTP status list does not define 299, so older versions could fail while parsing that unexpected response. Updating the integration fixed that specific incident, but seeing an authentication or setup failure today does not automatically mean the same bug has returned.
Check versions before changing your account
Open HACS, confirm that Alexa Media Player is installed from the official community repository, read the release notes, and compare its Home Assistant requirements. Restart Home Assistant after the update. Do not restore an old release blindly: Home Assistant Core and the alexapy dependency move together, and a downgrade can create a different incompatibility.
Separate HTTP 299 from current login failures
A current login loop, Amazon maplanding page, expired cookie, or two-step verification problem needs authentication troubleshooting. Confirm the Amazon marketplace domain, local callback URL, time synchronization, and authenticator-app method recommended by the project. Never paste a password, cookie, or TOTP secret into a public issue.
Safe recovery order
- Back up Home Assistant and the Alexa Media Player config entry.
- Update HACS metadata, the integration, and Home Assistant to mutually supported versions.
- Restart once and inspect the alexa_media and alexapy logs.
- Use Reconfigure before deleting the integration.
- If the problem remains, search the project’s current issues with exact version numbers and a sanitized log.
Why the integration can break again
Alexa Media Player is useful for announcements and media state, but it uses an unofficial Amazon interface. Amazon can change login and device endpoints without notice. Build important automations with fallbacks and avoid treating an Echo announcement as a safety-critical alert.
Frequently asked questions
Is HTTP 299 an Amazon server status I should allow through my firewall?
No. In this incident it was an unexpected response handled incorrectly by older code. Firewall changes are not the normal fix.
Should I delete Alexa Media Player and start over?
Only after a backup and after trying update, restart, and reconfiguration. Deleting first can remove useful evidence and force a difficult authentication flow.
Is Alexa Media Player an official Home Assistant integration?
No. It is a community custom integration commonly installed through HACS and it relies on an unofficial Alexa API.
Sources and revision policy
This guide uses Amazon support documentation and is written to remain useful when app labels change. Verify model-specific steps in the current official documentation.