How to recover when a call is refused

Read the error type first, then the message. A refusal that a retry cannot fix says so: a balance, a plan or a scope has to change. A removed endpoint answers 410 and names the call to make instead, rather than a 404 that only says something broke.

Last updated 31 August 2026

The call

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

TypeScript SDKts

import { InsufficientCredits, SourceUnavailable } from "@playhead/sdk";

try {
  await playhead.ask({ url, question: "what happens in this video" });
} catch (error) {
  if (error instanceof InsufficientCredits) {
    const { balance } = await playhead.credits();
    throw new Error(`${balance} credits left. Buying more is not a retry.`);
  }
  if (error instanceof SourceUnavailable) {
    // Private, geo-blocked or behind a login. Upload the file instead.
    const upload = await playhead.uploads.create(localCopy);
    await playhead.ask({ url: upload.upload_id, question: "what happens in this video" });
  } else {
    throw error;
  }
}

cURLbash

# The refusal itself tells you what to call instead.
{
  "error": {
    "type": "gone",
    "message": "This endpoint is no longer part of the product.",
    "alternative": "Ask a question with POST /v1/watch_video."
  }
}

Watch out for

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