How to recover when a call is refused

Read the suggestion field. When a window is too long for a detail level, the refusal carries the window that fits — as arguments, ready to spread straight back into the request. That is the difference between an agent that recovers on its own and one that reports a failure to a human.

Last updated 6 August 2026

The call

Copy this as it stands. “The API refused my window. What now?” is the question it answers.

TypeScript SDKts

import { WindowTooLong } from "@playhead/sdk";

try {
  await playhead.watch({ url, detail: "motion", start: 0, end: 5 });
} catch (error) {
  if (error instanceof WindowTooLong && error.suggestion) {
    // { start: 0, end: 3, detail: "motion" }
    await playhead.watch({ url, ...error.suggestion });
  } else {
    throw error;
  }
}

cURLbash

# The refusal itself tells you what to send instead.
{
  "error": {
    "type": "window_too_long_for_detail",
    "message": "motion is limited to 3s windows; you asked for 5s.",
    "suggestion": { "start": 0, "end": 3, "detail": "motion" },
    "max_window_seconds": 3
  }
}

Watch out for

Everything the API can refuse, and what to send instead, is on the errors page.