cli: surface error doc_url + param, fix rate-limit hint code

Add doc_url and param to the CLI error envelope, read from the API error envelope
and emitted only when present, so agents and users get the failing field and a link
to the error's documentation.

Fix the rate-limit hint: it was keyed on `rate_limited`, but the v3 API emits
`rate_limit_exceeded` (429), so real rate limits got no hint. Key the hint on
`rate_limit_exceeded` (and `quota_exceeded`), and align the 429 empty-code fallback
to `rate_limit_exceeded`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: somanshreddy

README.md

@@ -164,15 +164,15 @@ Every command supports `--help`.
 | Aspect | Behavior |
 |--------|----------|
 | **stdout** | Always JSON. Even `video download` — binary writes to disk; stdout emits `{"asset", "message", "path"}` so you can chain on `.path`. |
-| **stderr** | Structured envelope on error: `{"error": {"code", "message", "hint"}}`. Stable `code` values for programmatic branching. |
+| **stderr** | Structured envelope on error: `{"error": {"code", "message", "hint", "param", "doc_url", "request_id"}}`. `code`/`message` are always present; `hint`/`param`/`doc_url`/`request_id` appear when applicable (`param`/`doc_url` are surfaced from the API for validation and documented errors). Stable `code` values for programmatic branching. |
 | **Exit codes** | `0` ok · `1` API or network · `2` usage · `3` auth / not permitted · `4` timeout under `--wait` (stdout contains partial resource for resume) |
 | **Request bodies** | Flags for simple inputs; `-d` for nested JSON (inline, file path, or `-` for stdin). Flags override matching fields. |
 | **Async jobs** | `--wait` blocks with exponential backoff; `--timeout` sets max (default 20m). 429s and 5xx retry automatically. |
 
 Example error envelope:
 
 ```json
-{"error": {"code": "not_found", "message": "Video not found", "hint": "Check ID with: heygen video list"}}
+{"error": {"code": "not_found", "message": "Video not found", "hint": "Check ID with: heygen video list", "doc_url": "https://developers.heygen.com/docs/error-codes#not-found"}}
 ```
 
 ## Configuration

SKILL.md

@@ -69,7 +69,7 @@ heygen video get --response-schema
 ## Output Contract
 
 - **stdout**: JSON (always). This is the only output agents should consume.
-- **stderr**: JSON error envelope on failure: `{"error":{"code":"...","message":"...","hint":"..."}}`
+- **stderr**: JSON error envelope on failure: `{"error":{"code":"...","message":"...","hint":"...","doc_url":"...","param":"..."}}` (`hint`/`doc_url`/`param`/`request_id` present when applicable)
 - Do not pass `--human`. It produces unstructured text that cannot be parsed.
 
 ## Notes

internal/client/executor_test.go

@@ -257,7 +257,7 @@ func TestExecute_RetryOn429(t *testing.T) {
 		calls++
 		if calls == 1 {
 			w.WriteHeader(http.StatusTooManyRequests)
-			_, _ = w.Write([]byte(`{"error":{"code":"rate_limited","message":"too many requests"}}`))
+			_, _ = w.Write([]byte(`{"error":{"code":"rate_limit_exceeded","message":"too many requests"}}`))
 			return
 		}
 		w.WriteHeader(http.StatusOK)
@@ -292,7 +292,7 @@ func TestExecute_RetryPreservesBody(t *testing.T) {
 		calls++
 		if calls == 1 {
 			w.WriteHeader(http.StatusTooManyRequests)
-			_, _ = w.Write([]byte(`{"error":{"code":"rate_limited","message":"too many requests"}}`))
+			_, _ = w.Write([]byte(`{"error":{"code":"rate_limit_exceeded","message":"too many requests"}}`))
 			return
 		}
 		w.WriteHeader(http.StatusOK)
@@ -984,3 +984,16 @@ func TestParseErrorResponse_NonEnvelope_AuthExit(t *testing.T) {
 		})
 	}
 }
+
+// Integration: param/doc_url in an HTTP error body survive JSON parsing all the way
+// to the CLIError (not just when passed a pre-built APIError struct).
+func TestParseErrorResponse_SurfacesParamAndDocURL(t *testing.T) {
+	body := []byte(`{"error":{"code":"invalid_parameter","message":"bad value","param":"avatar_id","doc_url":"https://developers.heygen.com/docs/error-codes#invalid-parameter"}}`)
+	err := parseErrorResponse(400, body, "req_1")
+	if err.Param != "avatar_id" {
+		t.Errorf("Param = %q, want avatar_id", err.Param)
+	}
+	if !strings.Contains(err.DocURL, "error-codes") {
+		t.Errorf("DocURL = %q, want the doc URL", err.DocURL)
+	}
+}

internal/errors/errors.go

@@ -19,6 +19,8 @@ type CLIError struct {
 	Code      string // machine-readable: "auth_error", "not_found", "network_error"
 	Message   string // human-readable description
 	Hint      string // actionable fix: "Run heygen auth login"
+	Param     string // API: request field that caused the error (validation errors)
+	DocURL    string // API: link to this error code's documentation
 	RequestID string // from API X-Request-Id header (if applicable)
 	ExitCode  int    // process exit code (0/1/2/3/4)
 }
@@ -41,6 +43,12 @@ func (e *CLIError) ToErrorEnvelope() map[string]any {
 	if e.Hint != "" {
 		inner["hint"] = e.Hint
 	}
+	if e.Param != "" {
+		inner["param"] = e.Param
+	}
+	if e.DocURL != "" {
+		inner["doc_url"] = e.DocURL
+	}
 	if e.RequestID != "" {
 		inner["request_id"] = e.RequestID
 	}
@@ -133,7 +141,7 @@ func FromAPIError(statusCode int, apiErr *APIError, requestID string) *CLIError
 		}
 	case statusCode == 429:
 		if code == "" {
-			code = "rate_limited"
+			code = "rate_limit_exceeded"
 		}
 	case statusCode >= 500:
 		// A v3 app 5xx carries its own code (internal_error); a 5xx with no specific
@@ -165,10 +173,23 @@ func FromAPIError(statusCode int, apiErr *APIError, requestID string) *CLIError
 		hint = forbiddenHint
 	}
 
+	// Surface the API's own param / doc_url so agents and users get the field that
+	// failed and a link to the error's documentation (present only on API errors).
+	param := ""
+	if apiErr.Param != nil {
+		param = *apiErr.Param
+	}
+	docURL := ""
+	if apiErr.DocURL != nil {
+		docURL = *apiErr.DocURL
+	}
+
 	return &CLIError{
 		Code:      code,
 		Message:   message,
 		Hint:      hint,
+		Param:     param,
+		DocURL:    docURL,
 		RequestID: requestID,
 		ExitCode:  exitCode,
 	}
@@ -191,7 +212,7 @@ func hintForAPICode(code string) string {
 		return "Check your credit balance: heygen user me get. Purchase API credits: " + APIKeySettingsURL
 	case "invalid_parameter":
 		return "Use --request-schema on the command to see expected fields"
-	case "rate_limited":
+	case "rate_limit_exceeded", "quota_exceeded":
 		return "The CLI retries rate-limited requests automatically. If this persists, reduce request frequency"
 	case "resource_not_found", "not_found":
 		return "The requested resource does not exist. Retrying the same ID is unlikely to help"

internal/errors/errors_test.go

@@ -95,7 +95,7 @@ func TestFromAPIError_ExitCodes(t *testing.T) {
 		{"404 → not_found", 404, ExitGeneral, "not_found"},
 		{"409 → conflict", 409, ExitGeneral, "conflict"},
 		{"413 → payload_too_large", 413, ExitGeneral, "payload_too_large"},
-		{"429 → rate_limited", 429, ExitGeneral, "rate_limited"},
+		{"429 → rate_limit_exceeded", 429, ExitGeneral, "rate_limit_exceeded"},
 		{"500 → unclassified_server_error", 500, ExitGeneral, "unclassified_server_error"},
 		{"502 → unclassified_server_error", 502, ExitGeneral, "unclassified_server_error"},
 		{"503 → unclassified_server_error", 503, ExitGeneral, "unclassified_server_error"},
@@ -174,7 +174,8 @@ func TestHintForAPICode_AllMappedCodes(t *testing.T) {
 		{"voice_not_found", "heygen voice list"},
 		{"insufficient_credit", "heygen user me get"},
 		{"invalid_parameter", "--request-schema"},
-		{"rate_limited", "retries rate-limited"},
+		{"rate_limit_exceeded", "retries rate-limited"},
+		{"quota_exceeded", "retries rate-limited"},
 		{"resource_not_found", "does not exist"},
 		{"not_found", "does not exist"},
 		{"asset_not_available", "may still be processing"},
@@ -329,3 +330,35 @@ func TestConstructors(t *testing.T) {
 		}
 	})
 }
+
+func TestFromAPIError_SurfacesDocURLAndParam(t *testing.T) {
+	param := "avatar_id"
+	docURL := "https://developers.heygen.com/docs/error-codes#invalid-parameter"
+	apiErr := &APIError{Code: "invalid_parameter", Message: "bad value", Param: &param, DocURL: &docURL}
+	cliErr := FromAPIError(400, apiErr, "req_1")
+
+	if cliErr.Param != "avatar_id" {
+		t.Errorf("Param = %q, want avatar_id", cliErr.Param)
+	}
+	if cliErr.DocURL != docURL {
+		t.Errorf("DocURL = %q, want %q", cliErr.DocURL, docURL)
+	}
+
+	inner := cliErr.ToErrorEnvelope()["error"].(map[string]any)
+	if inner["param"] != "avatar_id" {
+		t.Errorf("envelope param = %v, want avatar_id", inner["param"])
+	}
+	if inner["doc_url"] != docURL {
+		t.Errorf("envelope doc_url = %v, want %q", inner["doc_url"], docURL)
+	}
+}
+
+func TestToErrorEnvelope_OmitsDocURLAndParamWhenEmpty(t *testing.T) {
+	inner := (&CLIError{Code: "network_error", Message: "x"}).ToErrorEnvelope()["error"].(map[string]any)
+	if _, ok := inner["param"]; ok {
+		t.Error("param should be omitted when empty")
+	}
+	if _, ok := inner["doc_url"]; ok {
+		t.Error("doc_url should be omitted when empty")
+	}
+}