[edridudi]

Step 4 of #6 — the last item on it.

Koios enforces a request body size limit on the bulk endpoints. Verified against live mainnet with 300 pool ids on /pool_info:

HTTP 413
Payload too large, body length was 18022. Please ensure your request body size is below 5120 bytes

Two things that check corrected, both of which I had been repeating from the v1.4.2 release notes:

• the limit is 5120 bytes, not ~6 KB
• the body is plain text, not JSON

Because it is text, the parser added in #210 correctly leaves Result.error null — so a caller got a bare 413 and had to already know that the remedy is to batch.

Change

A 413 now produces a KoiosError:

Field	Value
code	"413"
message	the server's text, verbatim
hint	Split the request into smaller batches and call the endpoint once per batch.

Nothing about the response is invented. The status is real, so synthetic stays false, and the message is Koios's own words including its byte counts. Only the remedy is ours, because Koios does not supply one — which is precisely the hint field's purpose.

Responses that already carry a JSON error are untouched; the parsed body always wins.

Testing

• a 413 carrying the exact live mainnet text → code, verbatim message, and a hint mentioning batches
• a 413 with an empty body → still gets a usable message and hint rather than nothing

mvn test -Dtest='*Preview*,BaseServiceErrorHandlingTest,ProposalDeserializationTest,*Bech32*'   # 143/143 pass
mvn verify -DskipTests                                                                          # javadoc clean

Closes #6.

🤖 Generated with Claude Code