Improve API error messages with centralized error handling

[quinn-diesel]

Summary

Introduces user-friendly error messages for common Buildkite API failures, particularly authentication (401) and authorization (403) errors. Users now receive clear, actionable guidance instead of raw HTTP error responses.

Changes

• ✅ Add handleAPIError() function for centralized error handling (pkg/buildkite/errors.go)
• ✅ Add comprehensive test coverage (pkg/buildkite/errors_test.go)
• ✅ Update all 14 tool implementations to use handleAPIError()
• ✅ Provide specific messages for:
  • 401 Unauthorized: "Authentication failed: Your API token is invalid or has expired. Please check your BUILDKITE_API_TOKEN and ensure it's still valid."
  • 403 Forbidden: "Permission denied: Your API token doesn't have the required permissions for this operation. [detailed message from API]"
• ✅ Include detailed error information from API RawBody when available

Benefits

• Better UX: Clear, actionable error messages guide users to solutions
• Faster debugging: Users immediately know if it's an auth issue vs other problems
• Maintainability: Single source of truth for error handling across all tools
• Consistency: All 14 tools now handle errors uniformly

Example

Before:

Error: GET https://api.buildkite.com/v2/organizations/acme: 401 Unauthorized []

After:

Authentication failed: Your API token is invalid or has expired. Please check your BUILDKITE_API_TOKEN and ensure it's still valid.

Testing

• ✅ Unit tests for 401, 403, 404, 500 status codes
• ✅ Tests for RawBody vs Message fallback logic
• ✅ Tests for non-Buildkite errors
• ✅ Helper function tests

Future Improvements (Post-Merge)

• Add 429 rate limit handling
• Add context cancellation/timeout messages
• Add structured logging for production debugging
• Expand test coverage for edge cases

Files Changed

• pkg/buildkite/errors.go (new)
• pkg/buildkite/errors_test.go (new)
• All 14 tool files in pkg/buildkite/ updated

🤖 Generated with Claude Code