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.

fetch, in TypeScriptts

const response = await fetch("https://api.tryplayhead.com/v1/watch_video", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PLAYHEAD_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url, question: "what happens in this video" }),
});
const body = await response.json();
if (body.error) {
  // The type says what to do. The message says it in words.
  if (body.error.type === "insufficient_credits") throw new Error("Buying credits is not a retry.");
  if (body.error.suggestion) console.log("Send this instead:", body.error.suggestion);
  throw new Error(`${body.error.type}: ${body.error.message}`);
}

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.