Give callers two error types, one extending the other

Fri, 28 Aug 2026 00:00:00 +0000

In the WazirX Java connector I split errors into two:

WazirxClientException — the caller made a mistake the caller can fix: a bad side value, a missing required field. Thrown before a request is even sent.
WazirxApiException — something went wrong once the request left the process: a network failure, a non-2xx response.

WazirxClientException extends WazirxApiException. That one line is the whole design. A caller who only cares “did this work?” catches the parent. A caller who wants to retry network failures but fail fast on their own bad input catches both separately. Nobody is forced into a giant catch (Exception e) that swallows bugs, and nobody has to try/catch five specific types at every call site.

Generic returns can be the right call for a library you maintain alone

Wed, 26 Aug 2026 00:00:00 +0000

The standard advice for a client library is: give callers typed responses. client.Ticker(...) (*Ticker, error), not (any, error). I went the other way in my WazirX Go connector and I still think it was right for that library.

The upstream API’s response shapes move around — objects that become arrays, fields that appear and vanish across endpoints. With ~25 endpoints and one maintainer (me, in spare hours), typed structs would mean 25 things to keep in sync with an API I don’t control and can’t see changes to until they ship. The generic return pushed that cost to the call site, where the caller already knows which two fields they want and can assert for them.

Engineering on Prateek Sharma

Give callers two error types, one extending the other

Generic returns can be the right call for a library you maintain alone