Errors

Every response carries success, data and error. On failure success is false, data is null, and error is an object:

{
  "success": false,
  "data": null,
  "error": {
    "status": 404,
    "message": "Engine 12 has no active prompt. Activate a prompt version first."
  }
}

error.status repeats the HTTP status inside the body, so a helper that returns only parsed JSON still knows what happened — without you threading the response object through every layer.

const response = await fetch(url, options);
const body = await response.json();

if (!body.success) {
  // status is in the body, so this works even where you only
  // kept the parsed JSON.
  if (body.error.status === 404) return fallbackPrompt();
  throw new Error(body.error.message);
}

Pick one to see the exact body it returns. Which of these a given endpoint can produce is listed on that endpoint's page.

A 500 means something went wrong on our side. Retrying is safe: these endpoints only read, so a retried call can never duplicate or half-apply anything.

A 401 or 404 will not fix itself on retry — the key or the engine ID needs changing first.

Sending no value for a variable is not a failure. The placeholder resolves to empty, the response is a 200, and the name appears in missing_variables. If you want that to be fatal in your own code, check that array and throw — the API deliberately doesn't decide for you.