feat: add proper error parsing and formatting

[ogzhanolguncu]

What does this PR do?

This PR parses and formats SDK errors for deploy CLI commands.

Fixes # (issue)

If there is not an issue for this, please create one first. This is used to tracking purposes and also helps us understand why this PR exists

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Chore (refactoring code, technical debt, workflow improvements)
• Enhancement (small improvements)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How should this be tested?

• Create a root key without needed permissions and make this call

go run . deploy  --project-id="proj_xx" --context="./demo_api" --env="production" --root-key="unkey_xxx" --api-base-url="http://localhost:7070"

• Also try to corrupt the command, try a random projectId or nonexisting rootKey.
• This will not handle wrong URL or some validations errors because those will be controlled by us not the users.

Checklist

Required

• Filled out the "How to test" section in this PR
• Read Contributing Guide
• Self-reviewed my own code
• Commented on my code in hard-to-understand areas
• Ran pnpm build
• Ran pnpm fmt
• Ran make fmt on /go directory
• Checked for warnings, there are none
• Removed all console.logs
• Merged the latest changes from main onto my branch with git pull origin main
• My changes don't cause any responsiveness issues

Appreciated

• If a UI change was made: Added a screen recording or screenshots to this PR
• Updated the Unkey Docs if changes were necessary

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dashboard	Ready	Preview, Comment	Feb 9, 2026 1:41pm
engineering	Ready	Preview, Comment	Feb 9, 2026 1:41pm

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Adds a new internal errors package with formatters for API error responses and integrates it into the deploy command to present formatted, user-facing error messages instead of raw errors.

Changes

Cohort / File(s)	Summary
Build Configuration cmd/deploy/BUILD.bazel, cmd/deploy/internal/errors/BUILD.bazel	Added //cmd/deploy/internal/errors to cmd/deploy deps; added Bazel go_library and go_test targets for the new errors package.
Error Formatting Implementation cmd/deploy/internal/errors/errors.go	New package providing FormatError(error) string and specific formatters for permission, authentication, not-found, and validation API error types; attaches metadata (Request ID, docs link).
Error Formatting Tests cmd/deploy/internal/errors/errors_test.go	New table-driven tests asserting formatted messages contain expected substrings for multiple API error scenarios.
Integration cmd/deploy/main.go	Imported and used the errors formatter when handling deployment errors; replaced raw error printing with formatted spinner output and adjusted return behavior to avoid duplicate output.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 41.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add proper error parsing and formatting' directly summarizes the main change in the changeset, which introduces error parsing and formatting functions for the deploy CLI.
Description check	✅ Passed	The description is mostly complete with a clear summary of changes, type of change marked, and detailed testing instructions provided. However, no issue number is referenced, and not all checklist items are completed.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch improve-cli-errors

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.5.0)

Command failed

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Flo4604]

see comment