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.

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

• auth_not_supported
• code_required
• invalid_auth_response
• invalid_token
• MCP server error

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

Appendix: 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)