Developer documentation

Errors and retry behavior

Distinguish loader exceptions, setup events and HTTP refusals inside the runtime.

Where errors appear

Channel	What to expect
Loader	mount/on/send can throw for an invalid element, UUID, command, event or payload. Auto-mount failures are logged in the host console.
Controller error event	A setup/session/bootstrap refusal with code and message. It has no HTTP status or Retry-After field.
Hosted player and network panel	Chat, media, capacity and later session failures may appear here without a host error event.

Observe setup errors

const unsubscribe = embed.on('error', ({ code, message }) => {
  console.error('RapidEye setup failed', code, message);
});
// On teardown: unsubscribe();

The example assumes an existing mounted controller named embed. Do not log bearer credentials, refresh credentials or private grants while collecting diagnostics.

Access and configuration refusals

Code	Meaning	Next action
embed_experience_unavailable / experience_unavailable	Missing, draft, revoked or unavailable experience.	Confirm the intended environment, publication and current revision.
viewer_grant_required	Private access needs a grant.	Supply a fresh grant from your authenticated server through the wrapper.
viewer_grant_invalid	Signature, fields, experience or expiry failed validation.	Check the server signing secret, exact payload and clock.
viewer_grant_replayed	This nonce was already claimed for the experience.	Issue a new grant and nonce; do not retry the same grant.
viewer_grant_unavailable	Private grant admission is unavailable. HTTP 503 refuses session creation.	Respect Retry-After. Obtain a fresh authorized grant for a later attempt; a lost response may have consumed the previous nonce.
refresh_invalid / refresh_expired / session_revoked	The runtime credential cannot continue.	Stop reusing credentials; use the runtime’s fresh authorized entry path.
embed_session_revoked	Backend refuses the viewer identity.	Confirm revocation/publication; do not replace credentials with an owner login.
capability_disabled	The current publication disables that operation.	Enable the intended capability, publish and reload.
embed_owner_not_approved / account_not_approved	Owner access is unavailable.	Ask the operator to check owner access.
embed_not_configured	Operator-side viewer authorization configuration is unavailable.	Report the environment and failure to the operator; do not add a key to your page.

Quota and service refusals

HTTP/code	Action
429 embed_usage_limit_exceeded	Wait for Retry-After, normally the remainder of the UTC day.
429 rate_limited	Respect Retry-After for the specific session/media/refresh limit.
503 embed_usage_unavailable	Shared chat quota unavailable; respect Retry-After before a bounded retry.
usage_limit_exceeded	Owner capacity exhausted; follow the returned retry interval.
usage_service_unavailable	Owner usage admission unavailable; retry only after service recovery or the returned interval.
signed_url_failed / variant_not_ready	Media lookup or processed variant unavailable; confirm processing and retry playback rather than repeatedly starting chat.

These are common current runtime codes, not an external provisioning REST specification. Retain the actual status, code and Retry-After when asking for help.

Troubleshooting checklist