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 (a plain x.y.z) says "this widget needs DeskDash x.y.z or newer":

• 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.

The store sets it for you. The app keeps a table of the release that last changed each part of the widget surface: every permission, setting type, setting key, preset, bundled font and manifest field, the bar kind, and one entry for everything no permission gates (ungated methods, the dd.* helpers, the dd-* components, tokens and events). Every new version you publish is stamped with the newest entry its manifest matches. A value you write yourself only counts when it is higher, and a published version keeps the floor it shipped with. Nothing to declare, and nothing to get wrong.

The releases behind the entries, for reference:

Because a permission's entry moves whenever that permission gains a method, an update of your widget can need a newer app than its previous version did even when your code did not change. The stamp shows on the upload's success screen and on your submissions page.