[edridudi]

Step 2 of #6.

Koios is served by PostgREST, which reports failures as a JSON object:

{"code":"42703","details":null,"hint":null,"message":"column record.no_such_column does not exist"}

Callers only ever saw that as an opaque String on Result.response, and had to parse it themselves to do anything useful — branch on the error, surface a message, or tell a client mistake from a server one.

Change

• New KoiosError model: code, message, details, hint
• New Result.error field, populated when a failing response carries a body of that shape

Nothing existing changes

Result.response is untouched and still holds the raw body, so no current caller behaves differently — Result.error is simply null where nothing was available before. That felt like the right trade given 1.22.1 already carries breaking changes; replacing response would have been cleaner but broken every consumer reading it today.

Two deliberate restraints:

• Bodies that are not JSON of that shape leave error null rather than guessing. A plain-text 500 gets getResponse() == "upstream failure" and getError() == null.
• Only the two sites where the body genuinely comes from the server parse it. The synthetic failures built locally — the invented 404 for an empty body, 500 for a null one, 400 from badRequestResult — do not fabricate a server error. Separating those properly is step 3 of Support Error Handling for All Relevant Endpoints #6.

Testing

Three new cases in the MockWebServer suite: a full PostgREST body parses to all four fields, a partial body parses what is present and leaves the rest null, and a plain-text body leaves error null while keeping the raw text.

mvn test -Dtest='*Preview*,BaseServiceErrorHandlingTest,ProposalDeserializationTest,*Bech32*'   # 141/141 pass

Also verified against live mainnet by filtering on a column that does not exist:

LIVE raw={"code":"42703","details":null,"hint":null,"message":"column record.no_such_column does not exist"}
LIVE parsed=KoiosError(code=42703, message=column record.no_such_column does not exist, details=null, hint=null)

🤖 Generated with Claude Code