Merge pull request #8573 from Shopify/gonzalo/device-authorization-gateway-retries

Retry gateway failures during device authorization

Author: gonzaloriestra

.changeset/handle-device-authorization-gateway-errors.md

@@ -0,0 +1,5 @@
+---
+'@shopify/cli-kit': patch
+---
+
+Retry gateway failures during device authorization before reporting an expected service error.

packages/cli-kit/src/private/node/api/status-checks.ts

@@ -0,0 +1,11 @@
+const GATEWAY_ERROR_STATUSES = new Set([502, 503, 504])
+
+/**
+ * Checks whether an HTTP status indicates a gateway-level failure.
+ *
+ * @param status - The HTTP status to check.
+ * @returns Whether the status is 502, 503, or 504.
+ */
+export function isGatewayErrorStatus(status: number | undefined): boolean {
+  return status !== undefined && GATEWAY_ERROR_STATUSES.has(status)
+}

packages/cli-kit/src/private/node/session/device-authorization.test.ts

@@ -7,18 +7,20 @@ import {clientId} from './identity.js'
 import {IdentityToken} from './schema.js'
 import {exchangeDeviceCodeForAccessToken} from './exchange.js'
 import {identityFqdn} from '../../../public/node/context/fqdn.js'
+import {recordRetry} from '../../../public/node/analytics.js'
 import {shopifyFetch} from '../../../public/node/http.js'
 import {isTTY} from '../../../public/node/ui.js'
 import {err, ok} from '../../../public/node/result.js'
-import {AbortError} from '../../../public/node/error.js'
-import {isCI, openURL} from '../../../public/node/system.js'
+import {AbortError, BugError} from '../../../public/node/error.js'
+import {isCI, openURL, sleep} from '../../../public/node/system.js'
 import * as output from '../../../public/node/output.js'
 
 import {beforeEach, describe, expect, test, vi} from 'vitest'
 import {Response} from 'node-fetch'
 
 vi.mock('../../../public/node/context/fqdn.js')
 vi.mock('./identity')
+vi.mock('../../../public/node/analytics.js')
 vi.mock('../../../public/node/http.js')
 vi.mock('../../../public/node/ui.js')
 vi.mock('./exchange.js')
@@ -160,7 +162,7 @@ describe('requestDeviceAuthorization', () => {
     expect(outputInfo).not.toHaveBeenCalledWith('👉 Press any key to open the login page on your browser')
   })
 
-  test('when the response is not valid JSON, throw an error with context', async () => {
+  test('when the response is not valid JSON, throw an error with context without retrying', async () => {
     // Given
     const response = new Response('not valid JSON')
     Object.defineProperty(response, 'status', {value: 200})
@@ -169,10 +171,121 @@ describe('requestDeviceAuthorization', () => {
     vi.mocked(identityFqdn).mockResolvedValue('fqdn.com')
     vi.mocked(clientId).mockReturnValue('clientId')
 
-    // When/Then
-    await expect(requestDeviceAuthorization(['scope1', 'scope2'])).rejects.toThrowError(
+    // When
+    const request = requestDeviceAuthorization(['scope1', 'scope2'])
+
+    // Then
+    await expect(request).rejects.toBeInstanceOf(BugError)
+    await expect(request).rejects.toThrowError(
       'Received invalid response from authorization service (HTTP 200). Response could not be parsed as valid JSON. If this issue persists, please contact support at https://help.shopify.com',
     )
+    expect(shopifyFetch).toHaveBeenCalledTimes(1)
+  })
+
+  test('retries a gateway response and returns once the service recovers', async () => {
+    // Given
+    vi.mocked(shopifyFetch)
+      .mockResolvedValueOnce(new Response('Service unavailable', {status: 503}))
+      .mockResolvedValueOnce(new Response(JSON.stringify(data), {status: 200}))
+    vi.mocked(identityFqdn).mockResolvedValue('fqdn.com')
+    vi.mocked(clientId).mockReturnValue('clientId')
+
+    // When
+    const got = await requestDeviceAuthorization(['scope1', 'scope2'])
+
+    // Then
+    expect(got).toEqual(dataExpected)
+    expect(shopifyFetch).toHaveBeenCalledTimes(2)
+    expect(sleep).toHaveBeenCalledOnce()
+    expect(sleep).toHaveBeenCalledWith(0.2)
+    expect(recordRetry).toHaveBeenCalledWith(
+      'https://fqdn.com/oauth/device_authorization',
+      'device-authorization-gateway-error',
+    )
+  })
+
+  test.each([
+    {retryAfter: '3', expectedDelay: 3},
+    {retryAfter: '0', expectedDelay: 0},
+    {retryAfter: 'Fri, 18 Sep 2026 12:00:10 GMT', expectedDelay: 10},
+    {retryAfter: 'Fri, 18 Sep 2026 11:59:59 GMT', expectedDelay: 0},
+    {retryAfter: 'invalid', expectedDelay: 0.2},
+    {retryAfter: '-1', expectedDelay: 0.2},
+    {retryAfter: '', expectedDelay: 0.2},
+    {retryAfter: '   ', expectedDelay: 0.2},
+  ])('uses $expectedDelay seconds for Retry-After "$retryAfter"', async ({retryAfter, expectedDelay}) => {
+    const now = vi.spyOn(Date, 'now').mockReturnValue(new Date('2026-09-18T12:00:00Z').getTime())
+    vi.mocked(shopifyFetch)
+      .mockResolvedValueOnce(new Response('Service unavailable', {status: 503, headers: {'Retry-After': retryAfter}}))
+      .mockResolvedValueOnce(new Response(JSON.stringify(data), {status: 200}))
+    vi.mocked(identityFqdn).mockResolvedValue('fqdn.com')
+    vi.mocked(clientId).mockReturnValue('clientId')
+
+    try {
+      const result = await requestDeviceAuthorization(['scope1', 'scope2'])
+
+      expect(result).toEqual(dataExpected)
+      expect(shopifyFetch).toHaveBeenCalledTimes(2)
+      expect(sleep).toHaveBeenCalledExactlyOnceWith(expectedDelay)
+    } finally {
+      now.mockRestore()
+    }
+  })
+
+  test('uses the Retry-After from each response and stops after two retries', async () => {
+    vi.mocked(shopifyFetch)
+      .mockResolvedValueOnce(new Response('Service unavailable', {status: 503, headers: {'Retry-After': '2'}}))
+      .mockResolvedValueOnce(new Response('Service unavailable', {status: 503, headers: {'Retry-After': '4'}}))
+      .mockResolvedValueOnce(new Response('Service unavailable', {status: 503, headers: {'Retry-After': '6'}}))
+    vi.mocked(identityFqdn).mockResolvedValue('fqdn.com')
+    vi.mocked(clientId).mockReturnValue('clientId')
+
+    await expect(requestDeviceAuthorization(['scope1', 'scope2'])).rejects.toBeInstanceOf(AbortError)
+
+    expect(shopifyFetch).toHaveBeenCalledTimes(3)
+    expect(sleep).toHaveBeenCalledTimes(2)
+    expect(sleep).toHaveBeenNthCalledWith(1, 2)
+    expect(sleep).toHaveBeenNthCalledWith(2, 4)
+  })
+
+  test.each([502, 503, 504])(
+    'when HTTP %i gateway responses persist, throw an expected error after two retries',
+    async (status) => {
+      // Given
+      vi.mocked(shopifyFetch).mockImplementation(async () => new Response('Service unavailable', {status}))
+      vi.mocked(identityFqdn).mockResolvedValue('fqdn.com')
+      vi.mocked(clientId).mockReturnValue('clientId')
+
+      // When
+      const request = requestDeviceAuthorization(['scope1', 'scope2'])
+
+      // Then
+      await expect(request).rejects.toBeInstanceOf(AbortError)
+      await expect(request).rejects.toThrowError(
+        `Received invalid response from authorization service (HTTP ${status}). The service may be experiencing issues. Response could not be parsed as valid JSON. If this issue persists, please contact support at https://help.shopify.com`,
+      )
+      expect(shopifyFetch).toHaveBeenCalledTimes(3)
+      expect(sleep).toHaveBeenNthCalledWith(1, 0.2)
+      expect(sleep).toHaveBeenNthCalledWith(2, 0.4)
+      expect(recordRetry).toHaveBeenCalledTimes(2)
+    },
+  )
+
+  test('preserves the existing error for a persistent JSON gateway response', async () => {
+    // Given
+    vi.mocked(shopifyFetch).mockImplementation(
+      async () => new Response(JSON.stringify({error: 'service_unavailable'}), {status: 503}),
+    )
+    vi.mocked(identityFqdn).mockResolvedValue('fqdn.com')
+    vi.mocked(clientId).mockReturnValue('clientId')
+
+    // When
+    const request = requestDeviceAuthorization(['scope1', 'scope2'])
+
+    // Then
+    await expect(request).rejects.toBeInstanceOf(BugError)
+    await expect(request).rejects.toThrowError('Failed to start authorization process')
+    expect(shopifyFetch).toHaveBeenCalledTimes(3)
   })
 
   test('when the response is empty, throw an error with empty body message', async () => {
@@ -206,7 +319,7 @@ describe('requestDeviceAuthorization', () => {
     )
   })
 
-  test('when the server returns a 500 error with non-JSON response, throw an error with server issue message', async () => {
+  test('when the server returns a 500 error with non-JSON response, throw an error without retrying', async () => {
     // Given
     const response = new Response('Internal Server Error')
     Object.defineProperty(response, 'status', {value: 500})
@@ -219,6 +332,7 @@ describe('requestDeviceAuthorization', () => {
     await expect(requestDeviceAuthorization(['scope1', 'scope2'])).rejects.toThrowError(
       'Received invalid response from authorization service (HTTP 500). The service may be experiencing issues. Response could not be parsed as valid JSON. If this issue persists, please contact support at https://help.shopify.com',
     )
+    expect(shopifyFetch).toHaveBeenCalledTimes(1)
   })
 
   test('when response.text() fails, throw an error about network/streaming issue', async () => {

packages/cli-kit/src/private/node/session/device-authorization.ts

@@ -1,11 +1,13 @@
 import {clientId} from './identity.js'
 import {exchangeDeviceCodeForAccessToken} from './exchange.js'
 import {IdentityToken} from './schema.js'
+import {isGatewayErrorStatus} from '../api/status-checks.js'
 import {identityFqdn} from '../../../public/node/context/fqdn.js'
+import {recordRetry} from '../../../public/node/analytics.js'
 import {shopifyFetch} from '../../../public/node/http.js'
 import {outputContent, outputDebug, outputInfo, outputToken} from '../../../public/node/output.js'
 import {AbortError, BugError} from '../../../public/node/error.js'
-import {isCI, openURL} from '../../../public/node/system.js'
+import {isCI, openURL, sleep} from '../../../public/node/system.js'
 
 import {Response} from 'node-fetch'
 
@@ -18,6 +20,9 @@ export interface DeviceAuthorizationResponse {
   interval?: number
 }
 
+const GATEWAY_ERROR_RETRY_LIMIT = 2
+const GATEWAY_ERROR_INITIAL_RETRY_DELAY_SECONDS = 0.2
+
 /**
  * Initiate a device authorization flow.
  * This will return a DeviceAuthorizationResponse containing the URL where user
@@ -34,22 +39,7 @@ export async function requestDeviceAuthorization(scopes: string[]): Promise<Devi
   const queryParams = {client_id: identityClientId, scope: scopes.join(' ')}
   const url = `https://${fqdn}/oauth/device_authorization`
 
-  const response = await shopifyFetch(url, {
-    method: 'POST',
-    headers: {'Content-type': 'application/x-www-form-urlencoded'},
-    body: convertRequestToParams(queryParams),
-  })
-
-  // First read the response body as text so we have it for debugging
-  let responseText: string
-  try {
-    responseText = await response.text()
-  } catch (error) {
-    throw new BugError(
-      `Failed to read response from authorization service (HTTP ${response.status}). Network or streaming error occurred.`,
-      'Check your network connection and try again.',
-    )
-  }
+  const {response, responseText} = await requestDeviceAuthorizationResponse(url, convertRequestToParams(queryParams))
 
   // Now try to parse the text as JSON
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -59,6 +49,9 @@ export async function requestDeviceAuthorization(scopes: string[]): Promise<Devi
   } catch {
     // JSON.parse failed, handle the parsing error
     const errorMessage = buildAuthorizationParseErrorMessage(response, responseText)
+    if (isGatewayErrorStatus(response.status)) {
+      throw new AbortError(errorMessage)
+    }
     throw new BugError(errorMessage)
   }
 
@@ -153,6 +146,60 @@ export async function pollForDeviceAuthorization(code: string, interval = 5): Pr
   })
 }
 
+async function requestDeviceAuthorizationResponse(
+  url: string,
+  body: string,
+  gatewayRetriesUsed = 0,
+): Promise<{response: Response; responseText: string}> {
+  const response = await shopifyFetch(url, {
+    method: 'POST',
+    headers: {'Content-type': 'application/x-www-form-urlencoded'},
+    body,
+  })
+
+  let responseText: string
+  try {
+    responseText = await response.text()
+  } catch {
+    throw new BugError(
+      `Failed to read response from authorization service (HTTP ${response.status}). Network or streaming error occurred.`,
+      'Check your network connection and try again.',
+    )
+  }
+
+  if (!isGatewayErrorStatus(response.status) || gatewayRetriesUsed >= GATEWAY_ERROR_RETRY_LIMIT) {
+    return {response, responseText}
+  }
+
+  const retryNumber = gatewayRetriesUsed + 1
+  const retryDelaySeconds =
+    retryAfterDelaySeconds(response.headers.get('retry-after')) ??
+    GATEWAY_ERROR_INITIAL_RETRY_DELAY_SECONDS * 2 ** gatewayRetriesUsed
+  recordRetry(url, 'device-authorization-gateway-error')
+  outputDebug(
+    `Scheduling device authorization retry #${retryNumber} after HTTP ${response.status} in ${retryDelaySeconds} seconds`,
+  )
+  await sleep(retryDelaySeconds)
+
+  return requestDeviceAuthorizationResponse(url, body, retryNumber)
+}
+
+function retryAfterDelaySeconds(retryAfter: string | null): number | undefined {
+  const value = retryAfter?.trim()
+  if (!value) return undefined
+
+  // Retry-After can specify either a delay in seconds or an HTTP date.
+  const delaySeconds = Number(value)
+  if (!Number.isNaN(delaySeconds)) {
+    return Number.isFinite(delaySeconds) && delaySeconds >= 0 ? delaySeconds : undefined
+  }
+
+  const retryAt = Date.parse(value)
+  if (Number.isNaN(retryAt)) return undefined
+
+  return Math.max(0, (retryAt - Date.now()) / 1000)
+}
+
 function convertRequestToParams(queryParams: {client_id: string; scope: string}): string {
   return new URLSearchParams(Object.entries(queryParams).filter(([, value]) => Boolean(value))).toString()
 }

packages/cli-kit/src/public/node/error/index.ts

@@ -2,6 +2,7 @@ import {normalizePath} from '../path.js'
 import {flushStdout, OutputMessage, stringifyMessage, TokenizedString} from '../output.js'
 import {tokenItemToString, type InlineToken, type TokenItem} from '../../../private/node/ui/components/token-item.js'
 import {hasRateLimitCode} from '../../../private/node/analytics/graphql-error-codes.js'
+import {isGatewayErrorStatus} from '../../../private/node/api/status-checks.js'
 
 import {Errors} from '@oclif/core'
 
@@ -249,7 +250,7 @@ function isExpectedApiError(error: Error): boolean {
     return false
   }
   const status = candidate.response.status
-  if (status === 401 || status === 429 || status === 502 || status === 503 || status === 504) {
+  if (status === 401 || status === 429 || isGatewayErrorStatus(status)) {
     return true
   }
   return hasRateLimitCode(candidate.response.errors)