Map NBP error statuses to specific errors with the status code

[milten89]

Fixes BACKLOG P0 item 3. Stacked on #14 (base fix/nbp-http-disposal). It will retarget to develop once #14 is merged.

Changes

Status mapping in GetNbpAsync, following ADR-0002:

Status	Before	After
400	UnknownError	new BadRequestError with the NBP message, e.g. 400 BadRequest - Przekroczony limit 255 wyników / Maximum size of 255 data series has been exceeded
401 / 403	UnknownError	UnauthorizedError
404	NotFoundError	NotFoundError
429	RateLimitExceededError	unchanged (with RetryAfter)
5xx	UnknownError	ServiceUnavailableError
other	UnknownError	UnknownError

• Every HTTP error stores the status code in Metadata[OpenUrzednikError.StatusCodeMetadataKey] (as int).
• Core API:
  • new BadRequestError / BadRequestException;
  • new public constant OpenUrzednikError.StatusCodeMetadataKey and a protected base constructor that takes a status code;
  • an optional int? statusCode = null parameter on NotFoundError, UnauthorizedError, ServiceUnavailableError, UnknownError and RateLimitExceededError. Callers' source still compiles, but binary compatibility breaks (the one-argument constructors are gone). That's acceptable before 1.0; put it in the release notes.
• Error body: at most 500 characters are read, through a StreamReader, so a large proxy/HTML body is never buffered. If the body can't be read, the error is returned without the server message and a guarded Debug log is written.
• Tests:
  • unit tests for every mapping, the server message, truncation and an unreadable body;
  • WireMock tests for 400/401/403/404/429/5xx, using 400 and 404 bodies captured from the real API (Nbp/Fixtures/error-*.txt). The real Content-Type is text/plain; charset=utf-8, checked with curl -D -.
• NbpFixtures.cs and the fixtures csproj item match Fix NBP table B rates failing against the real API #13, so the two merge cleanly. A small docs/BACKLOG.md conflict is expected; resolve it when rebasing.

Observed while capturing fixtures: the API's date-range limit is 367 days (400 … Limit of 367 days has been exceeded). The validators still enforce 93 days, which is backlog item 7.

Verification

• dotnet build OpenUrzednik.slnx: 0 errors (only the existing NU1902 warning).
• dotnet test -f net10.0: Core 79/79, Nbp 480/480, IntegrationTests 42 passed / 5 skipped (manual tests).
• dotnet format --verify-no-changes: clean.
• reviewer agent: no blocking findings. I fixed all of its should-fix points: the bounded read, the csproj conflict and the test assertions.

🤖 Generated with Claude Code