hcengineering/platform · error · PlatformError

platform.status.Forbidden

platform.status.Forbidden

Error message

Forbidden

What it means

The integration client maps HTTP 403 responses to PlatformError with status.Forbidden and message 'Forbidden'. Authentication succeeded, but the authenticated principal is not allowed to perform the requested operation.

Source

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

    }

    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. Verify the authenticated user/role has permission for this integration or resource.
2. Check whether the integration is disabled/suspended and re-enable it.
3. Confirm you are operating in the intended workspace/account.
4. Contact an admin to grant the required permission if it should be allowed.

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

try {
  await client.request(...)
} catch (err) {
  if (isForbidden(err)) {
    // show 'insufficient permissions' message; do not retry blindly
  } else {
    throw err
  }
}

When it happens

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

Common situations: Token valid but lacking permissions/roles for the resource; integration disabled or suspended server-side; trying to access another workspace's integration.

Understand the failure class

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

Related errors

• Forbidden
• Forbidden: read-only token
• You do not have write access to the target workspace. Owner
• Not an owner of workspace
• Missing auth info

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