hcengineering/platform · error · PlatformError

platform.status.Unauthorized

platform.status.Unauthorized

Error message

Unauthorized

What it means

The integration client maps HTTP 401 responses from the integration service to PlatformError with status.Unauthorized and message 'Unauthorized'. It means the request's bearer token was missing, expired, or rejected by the server.

Source

Thrown at packages/integration-client/src/request.ts:82

    if (contentLength === '0' || (!contentType.includes('application/json') && !contentType.includes('text/json'))) {
      return undefined
    }

    const text = await response.text()
    if (text.trim() === '') {
      return undefined
    }

    try {
      return JSON.parse(text)
    } catch (error) {
      console.warn('Failed to parse JSON response:', text, error)
      return undefined
    }
  } else if (response.status === 202) {
    return undefined
  } else if (response.status === 401) {
    throw new PlatformError(new Status(Severity.ERROR, platform.status.Unauthorized, {}))
  } else if (response.status === 403) {
    throw new PlatformError(new Status(Severity.ERROR, platform.status.Forbidden, {}))
  } else if (response.status === 404) {
    throw new PlatformError(
      new Status(Severity.ERROR, platform.status.ResourceNotFound, { resource: options.path ?? '' })
    )
  } else if (response.status >= 500) {
    throw new PlatformError(new Status(Severity.ERROR, platform.status.InternalServerError, {}))
  } else {
    throw new PlatformError(new Status(Severity.ERROR, platform.status.BadRequest, { status: response.status }))
  }
}

View on GitHub (pinned to 63e28dc964)

Solutions

1. Re-authenticate / refresh the token used by the client and retry.
2. Confirm the token is actually being passed (Authorization: Bearer header) for this request.
3. Check the token's audience/workspace matches the service you are calling.
4. If using a refresh callback, ensure it is invoked on 401 before giving up.

if (token == null || token === '') throw new Error('Auth token required for integration client')

function isUnauthorized (err: unknown): err is PlatformError {
  return err instanceof PlatformError && (err.status.code as number) === platform.status.Unauthorized
}

try {
  await client.request(...)
} catch (err) {
  if (isUnauthorized(err)) {
    await refreshToken()
    return client.request(...) // retry once with fresh token
  }
  throw err
}

When it happens

Trigger: Any request() call where the integration service responds with HTTP status 401.

Common situations: Expired or revoked auth token passed as token option; token issued for a different account/workspace; token never passed at all to an endpoint that requires it.

Understand the failure class

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

Related errors

• Unauthorized
• Couldn't find workspace with the provided token
• Unauthorized
• Missing account in token
• Missing workspace in token

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/4ebd827c262bfb05. Report an issue: GitHub.