mastra-ai/mastra · error

invalid API key or insufficient permissions

Error message

invalid API key or insufficient permissions

What it means

requestBrightData throws this when the Bright Data API responds with HTTP 401 or 403, meaning the API token was rejected or the account lacks permission for the requested zone/endpoint. The library treats both statuses as an authentication/authorization failure and aborts with this fixed message instead of the response body. It indicates the request reached Bright Data but credentials were not accepted.

Source

Thrown at integrations/brightdata/src/client.ts:72

  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), effectiveTimeout);

  try {
    const response = await fetch(REQUEST_ENDPOINT, {
      body: JSON.stringify(body),
      headers: {
        Authorization: `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      method: 'POST',
      signal: controller.signal,
    });

    const responseText = await response.text();

    if (!response.ok) {
      if (response.status === 401 || response.status === 403) {
        throw new Error('invalid API key or insufficient permissions');
      }

      if (response.status === 400) {
        throw new Error(`bad request: ${responseText}`);
      }

      throw new Error(`request failed with status ${response.status}: ${responseText}`);
    }

    if (body.format === 'json') {
      return responseText ? JSON.parse(responseText) : {};
    }

    return responseText;
  } catch (error) {
    if (error instanceof Error && error.name === 'AbortError') {
      throw new Error(`Request timed out after ${effectiveTimeout}ms`);
    }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify BRIGHTDATA_API_TOKEN (or the apiKey passed to getBrightDataClient) matches a valid token in the Bright Data dashboard.
2. Confirm the token has access to the configured zones (BRIGHTDATA_SERP_ZONE / BRIGHTDATA_WEB_UNLOCKER_ZONE or config serpZone/webUnlockerZone).
3. Test the token with a direct curl to the Bright Data endpoint to isolate library vs. credential issues.
4. If the token is valid but forbidden, check account status/billing and zone permissions in the Bright Data dashboard.

Example fix

// before
const client = getBrightDataClient({ apiKey: 'my-password' });
// after
const client = getBrightDataClient({ apiKey: process.env.BRIGHTDATA_API_TOKEN }); // real token from Bright Data dashboard

// before creating the client
const apiKey = configApiKey ?? process.env.BRIGHTDATA_API_TOKEN;
if (!apiKey || apiKey.length < 10) {
  throw new Error('BRIGHTDATA_API_TOKEN is missing or malformed');
}

try {
  const result = await client.search.google(query);
} catch (err) {
  if (err instanceof Error && err.message === 'invalid API key or insufficient permissions') {
    // surface an auth-config alert; do NOT retry — fix the token/zones first
    throw new Error('Check BRIGHTDATA_API_TOKEN and zone permissions');
  }
  throw err;
}

When it happens

Trigger: Any requestBrightData call (via client.search.google, etc.) where Bright Data returns status 401 or 403 — e.g. the Authorization header carried an invalid/expired/revoked token, the token lacks access to the configured serpZone/webUnlockerZone, or the account is blocked.

Common situations: BRIGHTDATA_API_TOKEN set to a placeholder or token from another account; token rotated/revoked while deploy env still holds the old value; zone deleted or renamed so the token's permissions no longer cover it; using a token type not permitted for the SERP API.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Token exchange failed: ${error}
• Failed to fetch user info from Clerk
• Google service account token request failed (${response.stat
• Failed to create account
• Auth check failed (${res.status})

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/57ab53fcab3741cd. Report an issue: GitHub.