DEVP-660: Improve 403 Forbidden error message with permission guidance

[shihanpan]

Summary

Improves the error message for 401 Unauthorized errors to clearly indicate both possible causes (invalid token OR insufficient permissions) and provide a link to documentation for resolving auth/permission issues.

Changes

• Enhanced _handle_auth_error() in exception_handler.py to clarify that 401 errors can be due to:
  • Invalid or expired API token
  • API client lacking required permissions for the operation
• Added direct link to Workato API client management documentation: https://docs.workato.com/api-mgmt/api-client-mgmt.html
• Restructured error message with clear sections: causes and resolution steps

Why

Users encountering 401 errors were receiving a message that only mentioned invalid tokens. However, 401 errors can also occur when the API key is valid but lacks sufficient permissions. This improvement makes the error more accurate and actionable.

Testing

• Error message displays both auth scenarios
• Documentation link is correct and accessible
• JSON output mode still works correctly

Related

• DEVP-822: Documents the broader issue of resource not found errors

🤖 Generated with Claude Code

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
__init__.py	68	4	94%	10–11, 69–70
cli
__init__.py	52	3	94%	49, 51, 60
containers.py	27	0	100%
cli/commands
__init__.py	0	0	100%
api_clients.py	291	9	96%	27, 302, 448–449, 483, 493, 584, 615, 623
api_collections.py	257	3	98%	28, 183, 347
assets.py	47	2	95%	55–56
connections.py	526	5	99%	591, 593, 599, 637, 988
data_tables.py	165	5	96%	31, 253, 267, 321–322
guide.py	166	1	99%	106
init.py	107	0	100%
profiles.py	203	0	100%
properties.py	97	1	98%	21
pull.py	172	2	98%	193–194
workspace.py	39	2	94%	61, 71
cli/commands/connectors
__init__.py	0	0	100%
command.py	90	2	97%	110, 159
connector_manager.py	203	4	98%	176, 292, 300–301
cli/commands/projects
__init__.py	0	0	100%
command.py	272	10	96%	359–362, 373, 439–441, 491, 495
project_manager.py	166	7	95%	48, 66, 263–264, 276, 317, 325
cli/commands/push
__init__.py	0	0	100%
command.py	133	4	96%	109, 112, 230, 308
cli/commands/recipes
__init__.py	0	0	100%
command.py	427	9	97%	117, 133–134, 272–275, 403, 709
validator.py	706	20	97%	174, 883, 1136, 1223, 1246, 1279, 1281–1282, 1359–1361, 1457–1458, 1517–1518, 1707–1708, 1736–1738
cli/utils
__init__.py	4	0	100%
exception_handler.py	327	27	91%	134–135, 140–141, 143–144, 174–175, 181, 184–185, 228, 283, 311, 338, 395, 430, 489, 491–492, 497–498, 500–504
gitignore.py	14	0	100%
ignore_patterns.py	23	0	100%
spinner.py	43	0	100%
token_input.py	45	17	62%	70, 98, 100, 102–104, 107, 124, 127–128, 132–133, 136, 139–140, 142, 144
version_checker.py	135	6	95%	24, 26, 33–34, 72, 102
cli/utils/config
__init__.py	5	0	100%
manager.py	544	34	93%	127, 138, 149, 157–159, 162, 165, 177, 227–228, 399, 417, 421, 424–427, 443, 464, 478, 491, 533, 574, 652–653, 690, 904, 1047–1048, 1062–1063, 1119, 1178
models.py	33	0	100%
profiles.py	309	10	96%	93, 189–190, 193, 228–230, 255–257
workspace.py	68	0	100%
TOTAL	5764	187	96%