Common issues

401 unauthorized

#

This usually means one of three things:

1. you used a Bearer token where Basic auth was required for POST /tokens
2. the Bearer token is missing, expired in storage, or copied incorrectly
3. your automation is pointed at the wrong BrowserBee environment

404 when reading a browser profile

#

The profile key in the URL does not match an existing BrowserBee profile.

Verify:

• the profile_key value
• whether the profile was deleted
• whether your automation is still targeting an older key after a rename or migration

422 on profile creation or update

#

Validation failures are usually caused by malformed request bodies or unsupported enum values.

Check:

• channel is one of stable, beta, or nightly
• status is one of available, preview, or deprecated
• arrays such as capabilities and platforms are sent as JSON arrays

Webhook receiver never sees deliveries

#

Start with these checks:

1. list your registered webhooks with GET /webhooks
2. confirm the webhook is still active
3. verify the destination URL is reachable from the public internet
4. confirm your receiver still has the stored signing secret for the webhook

Readiness endpoint returns 503

#

GET /ready reports dependency failures. If your integration checks BrowserBee readiness before rollout, treat 503 as a signal to pause downstream work until the service is healthy again.

Deprecated profile still in use

#

Deprecation is a migration warning, not an outage. The safest customer response is:

1. identify the consuming pipeline or team
2. create or confirm the replacement profile
3. migrate automation to the replacement key
4. delete the deprecated profile only after usage is removed