alibaba/page-agent · critical · InvokeError

AUTH_ERROR

AUTH_ERROR

Error message

Authentication failed: ${errorMessage}

What it means

The endpoint returned HTTP 401 or 403, meaning the API key is missing, invalid, expired, or lacks permission for the requested resource/model. The message embeds the provider's error message from the response body (or statusText as fallback), and the parsed error body is attached as details.

Source

Thrown at packages/llms/src/OpenAIClient.ts:102

			})
		} catch (error: unknown) {
			if ((error as any)?.name === 'AbortError') throw error
			console.error(error)
			throw new InvokeError(InvokeErrorTypes.NETWORK_ERROR, 'Network request failed', error)
		}

		// 3. Handle HTTP errors
		if (!response.ok) {
			let errorData: any
			try {
				errorData = await response.json()
			} catch (error) {
				if ((error as any)?.name === 'AbortError') throw error
			}
			const errorMessage = errorData?.error?.message || response.statusText

			if (response.status === 401 || response.status === 403) {
				throw new InvokeError(
					InvokeErrorTypes.AUTH_ERROR,
					`Authentication failed: ${errorMessage}`,
					errorData
				)
			}
			if (response.status === 429) {
				throw new InvokeError(
					InvokeErrorTypes.RATE_LIMIT,
					`Rate limit exceeded: ${errorMessage}`,
					errorData
				)
			}
			if (response.status >= 500) {
				throw new InvokeError(
					InvokeErrorTypes.SERVER_ERROR,
					`Server error: ${errorMessage}`,
					errorData
				)

View on GitHub (pinned to d02db1ee7c)

Solutions

1. Verify the API key is set, non-empty, and copied exactly (no quotes/newlines)
2. Confirm the key matches the provider implied by baseURL — OpenAI keys don't work on Azure/Gemini/other compatible endpoints
3. For Azure-style endpoints, ensure the auth header and deployment name required by that provider are configured (via transformRequestHeaders/requestBody)
4. Test the key directly: curl -H "Authorization: Bearer $KEY" <baseURL>/models
5. If 403 on a specific model, switch to a model your account is entitled to

Example fix

// before
const client = new OpenAIClient({ baseURL: 'https://api.openai.com/v1', apiKey: undefined })

// after
const client = new OpenAIClient({
  baseURL: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY!, // ensure it is loaded and trimmed
})

if (!cfg.apiKey || cfg.apiKey.trim().length < 20) {
  throw new Error('API key missing or suspiciously short')
}

const isAuthError = (e: unknown): e is InvokeError =>
  e instanceof InvokeError && e.code === 'AUTH_ERROR'

try {
  await client.invoke(req)
} catch (e) {
  if (isAuthError(e)) {
    // keys rarely heal — surface to user, do not retry
    throw new Error(`Check your API key: ${e.message}`)
  }
  throw e
}

When it happens

Trigger: invoke() call where the server responds 401 (bad/missing API key) or 403 (key valid but forbidden — model not entitled, org restricted, or region blocked). Common with OpenAI, Azure (wrong deployment/key header), Gemini OpenAI-compat endpoints with an invalid key.

Common situations: API key env var not set or pasted with whitespace/quotes; using an OpenAI key against an Azure or Gemini baseURL; free-tier key requesting a paid model; expired or revoked token; wrong apiKeyHeader configuration for a compatible provider.

Understand the failure class

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

Related errors

• CONFIG_ERROR
• NETWORK_ERROR
• RATE_LIMIT
• SERVER_ERROR
• UNKNOWN

AI-assisted analysis of alibaba/page-agent@d02db1ee7c (2026-08-28). Data as JSON: /api/errors/0d6e63ce2f7c2587. Report an issue: GitHub.