fix: Hint at api.name config when 404 source mismatches CLI config

[kfelternv]

Based on a few bug reports, adding a small hint to direct users to the api.name configuration option would help debug 404s when using the cli with nico rest

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Walkthrough

This PR adds diagnostic guidance for API configuration mismatches. The APIError struct gains an optional Hint field that formats into error messages. A new helper detects 404 responses where the server-provided source differs from the client's configured API name and generates a remediation suggestion. The client wires this detection into its error path, and tests validate the logic across matching, mismatching, and edge cases.

Changes

API name mismatch hint feature

Layer / File(s)	Summary
APIError type and error formatting cli/pkg/client.go	APIError struct now exports optional Hint field; Error() method conditionally appends Hint: ... line to formatted error message when hint is non-empty.
API name mismatch hint detection and client integration cli/pkg/client.go	New apiNameMismatchHint() helper detects 404 responses with source mismatch and returns configuration suggestion. Client's HTTP error path calls this helper and assigns the result to APIError.Hint before returning.
Test coverage for hint detection and error formatting cli/pkg/client_test.go	Table-driven test for hint detection validates 404 vs. non-404 handling and matching/mismatching source values. Integration tests verify Client.Do propagates hints correctly and that APIError.Error() formatting includes Hint: section only when hint is non-empty.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description relates directly to the changeset, explaining the motivation for adding the api.name configuration hint for debugging 404 errors.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title directly addresses the core change: adding a helpful hint when a 404 response indicates an API name configuration mismatch.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

🔐 TruffleHog Secret Scan

✅ No secrets or credentials found!

Your code has been scanned for 700+ types of secrets and credentials. All clear! 🎉

🔗 View scan details

_{🕐 Last updated: 2026-05-15 19:12:19 UTC | Commit: 23cabcd}

[github-actions]

🔍 Container Scan Summary

Service	Total	Critical	High	Medium	Low	Other
nico-flow	66	4	34	18	2	8
nico-nsm	82	2	28	43	9	0
nico-psm	67	4	35	18	2	8
nico-rest-api	100	6	53	30	3	8
nico-rest-cert-manager	65	4	34	18	1	8
nico-rest-db	66	4	34	18	2	8
nico-rest-site-agent	65	4	34	18	1	8
nico-rest-site-manager	65	4	34	18	1	8
nico-rest-workflow	67	4	35	18	2	8
TOTAL	643	36	321	199	23	64

Per-CVE detail lives in the per-service grype-* artifacts (JSON + SARIF). Severity counts only — no CVE IDs published here.

[thossain-nv]

@kfelternv Could this confuse those who are using /forge?

[thossain-nv]

So the API will return a json structure for 404 responses where the source field is set to the API name, we could just hint that?

[thossain-nv]

Looks good, thanks for the changes @kfelternv