feat(apiclient): RFC 9457 Problem Details on v2 error responses

[jhagberg]

Related issue(s) and PR(s)
Closes #678. Stacks on #686. Fifth of five PRs for #663.

Description
Replaces V2Client's ad-hoc "server returned status N: {body}" error format with RFC 9457 Problem Details parsing, adds a typed APIError with StatusCode for errors.As-based callers, and drops the substring-match hack in V2Client.DownloadFile's 403-flatten logic. Small PR (+205 / −13), focused on the error surface; success path unchanged.

Key design points

• apiclient.APIError is a typed error with StatusCode (so callers can errors.As), an optional *ProblemDetails populated when the body parses, and a truncated Body for diagnostics. The msg field stays unexported so the formatted message always goes through Error().
• parseErrorResponse tries Problem Details when Content-Type is application/problem+json or application/json (case-insensitive via mime.ParseMediaType). Falls back to "server returned status N: <truncated>" for HTML / plain / empty / malformed. Body read capped at 8 KiB.
• V2Client.DownloadFile's resolve-step 403 flatten moves from strings.Contains(err.Error(), "status 403") to errors.As(err, &apiErr) && apiErr.StatusCode == http.StatusForbidden. The old substring match silently stopped firing the moment the server started returning Problem Details — the new message contains "Forbidden (403)", never "status 403" — so the 403 would have leaked. This PR is what getJSON's // #678 replaces error wrapping... comment was waiting for.
• Both 403 flatten sites still produce "dataset/file does not exist or access denied: <UserArg>"; the typed *APIError message is discarded on that path so the leakage contract can't leak Problem Details detail.

User-visible CLI message change (worth flagging at review)

Non-403 v2 server responses change shape. Dev stack returns application/problem+json, so:

• Old: Error: failed to get datasets, reason: server returned status 401: {"detail":"Missing, invalid, or expired bearer token.",...}
• New: Error: failed to get datasets, reason: Unauthorized (401): Missing, invalid, or expired bearer token.

403 flattening is unchanged. Shell scripts or log filters keyed on the literal "server returned status N" need updating for the Problem-Details path.

Out of scope (tracked separately)

• Required-field validation on v2File (deferred Codex finding).
• Clean "invalid base URL" shape for empty/malformed BaseURL on v2.
• N+1 re-resolve on datasetCase / recursiveCase (carried from feat(download): v2 file download via /files/{fileId} #686).

How to test

Local:

• go build ./..., go vet ./..., gofmt -l .: clean.
• go test ./...: 191 pass.
• golangci-lint run --timeout 5m: 0 issues.

Integration (build tag integration, against the live v2 dev stack):

• TestV2_ListDatasets_Smoke, TestV2_ListFiles_Smoke, TestV2_ListFiles_ExactPath_Smoke, TestV2_ListFiles_PathPrefix_NoMatch, TestV2_DatasetInfo_Smoke, TestV2_DownloadFile_EndToEnd, TestV2_DownloadFile_NotFound403: 7/7 pass.

Manual against the live dev stack:

• list --api-version v2 --dataset EGAD_FORBIDDEN → "Forbidden (403): access denied" (typed; list has no leakage flatten).
• list --api-version v2 --datasets with fake-signature JWT → "Unauthorized (401): Missing, invalid, or expired bearer token."
• download --api-version v2 --dataset-id EGAD_DOES_NOT_EXIST --pubkey <pem> some-file.c4gh → "dataset/file does not exist or access denied: some-file.c4gh" (403 on list-resolve via the typed errors.As path — would have leaked under the old substring hack).
• Same with bare fileId → same flatten message.
• Happy path by-path and by-fileId still produces canonical filename.

Test plan

• go test ./...: 191 pass
• go vet ./...: clean
• golangci-lint run: clean
• gofmt -l .: clean
• Integration: 7/7 pass against live dev stack
• Manual: typed 401/403, ambiguous-403 flatten via errors.As, happy path unchanged
• CI: golint, test (ubuntu + windows), integration-v2, integration (s3), codeql-analysis

[nanjiangshu]

Nice work. Added a minor comment regarding potential problems when truncating byte strings.