Errors and versioning

Error codes

Every failed bridge call rejects with an Error carrying a code:

Handle errors like any other rejected promise, and degrade instead of crashing:

try {
  await dd.media.playPause();
} catch (err) {
  if (err.code === "RATE_LIMITED") return;  // ignore, the user is mashing
  dd.log("warn", "playPause failed", err.code);
}

Timeouts: the SDK rejects requests client-side after 15 seconds, except the dd.dialogs.* pickers, which wait on the user (the host guarantees they settle: a 1 hour backstop plus force-cancel on edit mode, reload, and removal).

apiVersion: the bridge contract

Your manifest's apiVersion declares which bridge API the widget was written against. The host runs everything in the range [minSupported ..= version]; both numbers ride context.api and are currently both 1.

• Newer than the host: the manifest is quarantined at scan ("requires a newer dashboard") and the widget never loads.
• Older than minSupported: the widget stays listed, but its instances render a "needs an update" tile instead of mounting, and every bridge call would fail GONE.

Deprecation, then removal

API surface is never removed silently:

1. A method (or a change in its output) is first deprecated. It keeps working for at least one release; the SDK warns once per method in your own console ([dd] <method> is deprecated: <note>), and the current table rides context.api.deprecated.
2. When apiVersion bumps, deprecated methods move to removed: calls reject with GONE and a message naming the replacement.

Rules of thumb: watch your console during development, treat any [dd] deprecation warning as a to-do before the next API bump, and feature-detect with context.api.version when one widget build should span versions.

minAppVersion: the feature floor

minAppVersion and apiVersion gate different things. apiVersion is the bridge contract. minAppVersion (optional, a plain x.y.z) says "this widget uses a permission or capability first shipped in DeskDash x.y.z":

• An app older than the floor quarantines the manifest with "needs DeskDash x.y.z or newer" instead of a raw parse error.
• The marketplace shows such a listing with a "Needs app update" chip and a disabled Install button.

Declare it whenever the widget uses something newer than the oldest app you intend to support. Current floors worth knowing:

The store validators enforce the floors they know about, so a submission missing one fails validation rather than breaking on users.