Error Handling

{
  "error": {
    "code": "namespace.specific_code",
    "message": "human-readable message",
    "meta": { "field": "..." }
  },
  "request_id": "a1b2c3d4"
}

err = response.json()["error"]
code = err["code"]
if code == "account.reconnection_required" or \
   (code.startswith("platform.") and code.endswith(".auth")):
    redirect_to_reconnect(account_id)

const resp = await fetch(`https://api.social-api.ai/v1/accounts/${accountId}/comments`, {
  headers: { Authorization: `Bearer ${apiKey}` }
});

if (!resp.ok) {
  const body = await resp.json();
  const { code, message, meta } = body.error;
  const requestId = body.request_id; // include in support reports

  // Reconnect dead OAuth tokens
  if (code === "account.reconnection_required" ||
      (code.startsWith("platform.") && code.endsWith(".auth"))) {
    await reconnectAccount(accountId);
    return;
  }

  // Upstream platform throttling: retry with backoff
  if (code.startsWith("platform.") && code.endsWith(".rate_limit")) {
    await sleep(60_000);
    return retry();
  }

  // Plan limits: prompt to upgrade
  if (code.startsWith("billing.")) {
    throw new Error(`Plan limit hit: ${message}`);
  }

  // BYOK setup needed
  if (code === "byok.credentials_missing") {
    showByokSetupModal(meta?.platform);
    return;
  }

  // Operation not supported on this platform
  if (code === "resource.not_supported") {
    console.warn(`Not supported: ${message}`);
    return null;
  }

  throw new Error(`API error: ${message} (${code}) [request_id: ${requestId}]`);
}