Skip to main content

Troubleshooting

Find your symptom, check the cause, apply the fix. Every HTTP error also carries a stable code; the full list is in responses and errors.

Camera, microphone and screen​

The browser never asks for the camera or microphone​

Cause: browsers only allow media capture on secure pages. Fix: serve the app over HTTPS, or use http://localhost while developing.

Permission was denied​

Cause: the user, or a browser or OS setting, blocked access. Fix: ask the user to allow the camera and microphone for your site in the browser's site settings, and on macOS check System Settings → Privacy & Security. Show a clear message and a retry button instead of failing silently. The recovery guide covers retry flows per SDK.

There's no screen-share option on a phone​

Cause: most mobile browsers, including Safari on iOS, don't support screen capture from a web page. Fix: offer screen sharing on desktop browsers, or use a native SDK (Flutter, React Native, Android, Swift) where the platform allows it.

Audio and video​

I joined but hear nothing​

Cause: browsers block audio from playing until the user interacts with the page. In a custom or headless UI, remote audio may not be rendered at all. Fix: join from a user action such as a button click. If you build your own UI, render every remote audio stream; see media lifecycle and headless mode.

Video appears for some people but not others​

Cause: in large rooms only a page of participants is shown and sent at a time, and paused streams stop sending. Fix: check pagination and paused-stream handling in large rooms and moderation.

Rooms and the API​

401 UNAUTHORIZED​

Cause: the Authorization header is missing or malformed, or the key is wrong. Fix: send exactly Authorization: Bearer <api-username>:<api-key>, with a colon between the two values and no extra spaces. Copy both again from API keys.

403 FORBIDDEN​

Cause: the request came from a domain that isn't on your allowed list, or a disposable key was used for an operation outside its scope. Fix: add your app's hostname with the domains API or in the dashboard, route the request through your backend, or create a disposable key with the scope you need.

409 CONFLICT when creating a room​

Cause: the host userName is already hosting an active room. Fix: use a different userName, or end the existing room first.

A retried create made two rooms​

Cause: the first request succeeded but the response was lost. Fix: send an Idempotency-Key header with each create, reusing it on retry. See Keep API keys on your backend.

People can't join: the room is full​

Cause: the room reached its capacity, or its type's limit (a chat room holds two people). Fix: create the room with a larger capacity or a type that fits. See room types.

The room closed early​

Cause: its duration ran out, or the host ended it. Fix: create rooms with a duration that covers the session, up to 1440 minutes.

429 RATE_LIMITED​

Cause: too many requests in a short time. Fix: back off and retry with increasing delays.

Recording and streaming​

A recording is missing​

Cause: completed recordings stay in MediaSFU staging for 72 hours, then they are deleted. Fix: download recordings within 72 hours, or configure your own storage. The recordings API lists what's available.

A streaming request is declined​

Cause: the room has ended, the source has no video, or streaming isn't enabled for the account. Fix: check the room is running and the source is active. See Streaming. RTMP, RTMPS and SRT are not enabled by default; contact support@mediasfu.com to discuss access.

Still stuck?​

Try the request in the API Sandbox to separate code problems from account problems, or email support@mediasfu.com with the error code, the room ID and the time it happened. Never include your API key.