gildas-lormeau/SingleFile · error · Error

unknown_error

unknown_error

Error message

unknown_error (" + httpResponse.status + ")

What it means

getResponse's fallback branch: any HTTP status other than 200/404/401 is thrown as "unknown_error (<status>)". This covers 4xx/5xx statuses the library does not specifically map — 403 (forbidden/quota), 429 (rate limit), 5xx (Google server errors), etc. The numeric status is embedded in the message, so parse it to decide on retry behavior.

Source

Thrown at src/lib/gdrive/gdrive.js:491

async function getJSON(httpResponse) {
	httpResponse = getResponse(httpResponse);
	const response = await httpResponse.json();
	if (response.error) {
		throw new Error(response.error);
	} else {
		return response;
	}
}

function getResponse(httpResponse) {
	if (httpResponse.status == 200) {
		return httpResponse;
	} else if (httpResponse.status == 404) {
		throw new Error("path_not_found");
	} else if (httpResponse.status == 401) {
		throw new Error("invalid_token");
	} else {
		throw new Error("unknown_error (" + httpResponse.status + ")");
	}
}

View on GitHub (pinned to 517fb7c5cf)

Solutions

1. Parse the status from the message (e.g. /unknown_error \((\d+)\)/) and branch: retry on 429/5xx with exponential backoff, surface 403 as a permissions problem to the user.
2. For 403, verify OAuth scopes and Drive sharing/permissions for the target resource.
3. Respect Retry-After headers for 429 by slowing or queueing requests.
4. Check Google Workspace Status Dashboard if 5xx errors cluster in time.

Example fix

// before
await gdrive.getJSON(resp); // Error: unknown_error (429)
// after
try {
  await gdrive.getJSON(resp);
} catch (e) {
  const m = /unknown_error \((\d+)\)/.exec(e.message);
  if (m && (m[1] === "429" || m[1].startsWith("5"))) {
    await new Promise(r => setTimeout(r, 2000));
    return retry();
  }
  throw e;
}

function parseUnknownStatus(e) {
  const m = /unknown_error \((\d+)\)/.exec(String(e.message));
  return m ? Number(m[1]) : null;
}

try { await gdrive.getJSON(resp); }
catch (e) {
  const status = parseUnknownStatus(e);
  if (status === 429 || (status && status >= 500)) return retryWithBackoff();
  if (status === 403) showPermissionsHelpToUser();
  throw e;
}

When it happens

Trigger: Drive API returns 403 (insufficient permissions, sharing policy, or quota exceeded), 429 (rate limiting), or 500/502/503 (Google-side outage); transient network proxies returning non-200 statuses; requests to endpoints that moved.

Common situations: Bulk operations hammering the API into 403 rateLimitExceeded; app lacking scope for the operation (403); Google incidents causing 5xx bursts; corporate proxies intercepting traffic.

Related errors

• unknown_token
• invalid_auth_response
• auth_not_supported
• code_required
• upload_cancelled

AI-assisted analysis of gildas-lormeau/SingleFile@517fb7c5cf (2026-09-01). Data as JSON: /api/errors/df67d0f2ff98633b. Report an issue: GitHub.