Repository navigation
Implement unified response parser #12
Description
Description
All resource methods should go through a single _parse_response(response) function that handles JSON decoding, success detection, and mapping HTTP error codes to the correct typed exceptions. This prevents per-resource error handling drift.
Proposed Steps
- Create
_parse_response(response: httpx.Response) -> dictinhttp_client.py. - On 2xx: decode JSON and return the dict.
- On 401: raise
AuthenticationError. - On 400 / 422: raise
InvalidRequestErrorwith field-level errors if present. - On 404: raise
NotFoundError. - On 429: raise
RateLimitError. - On 5xx: raise
NetworkError(subject to retry). - On JSON decode failure: raise
ShadeError("Invalid response from API").
Acceptance Criteria
- Every 4xx/5xx response is mapped to the correct exception type.
- The raw response body and HTTP status are accessible on every exception.
- A non-JSON response body raises
ShadeErrorrather than crashing with a rawJSONDecodeError. - 2xx responses that contain an
errorkey in the body are still treated as errors.
Activity
KodeSage commentedon Jun 23, 2026
I have experience building backend SDKs, API clients, and integrations where consistency in error handling and response processing is critical. I’ve worked with HTTP clients, typed exceptions, request/response validation, and designing reusable abstractions to prevent duplicated logic across resources.
For this issue, I would first review the existing http_client.py flow and how individual resource methods currently process responses. I would introduce a centralized _parse_response(response: httpx.Response) method responsible for decoding responses, detecting success/error states, and mapping HTTP failures into the correct custom exception types.
The implementation would ensure all 2xx responses are validated for API-level errors, while 4xx and 5xx responses are consistently converted into typed exceptions such as AuthenticationError, InvalidRequestError, NotFoundError, RateLimitError, and NetworkError. I would preserve useful debugging context by attaching the raw response body and status code to every raised exception.
KodeSage commentedon Jun 23, 2026
I have experience building backend SDKs, API clients, and integrations where consistency in error handling and response processing is critical. I’ve worked with HTTP clients, typed exceptions, request/response validation, and designing reusable abstractions to prevent duplicated logic across resources.
For this issue, I would first review the existing http_client.py flow and how individual resource methods currently process responses. I would introduce a centralized _parse_response(response: httpx.Response) method responsible for decoding responses, detecting success/error states, and mapping HTTP failures into the correct custom exception types.
The implementation would ensure all 2xx responses are validated for API-level errors, while 4xx and 5xx responses are consistently converted into typed exceptions such as AuthenticationError, InvalidRequestError, NotFoundError, RateLimitError, and NetworkError. I would preserve useful debugging context by attaching the raw response body and status code to every raised exception.
grantfox-oss commentedon Jun 23, 2026
🦊 GrantFox — @KodeSage has been assigned to this issue as part of the Official Campaign campaign!
Next steps:
Closes #12)Good luck! Track your progress on GrantFox.
grantfox-oss commentedon Jun 29, 2026
🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!
@KodeSage's PR #32 was approved and merged by @codebestia.
🏆 @KodeSage: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (51 total points). Track your full progress on GrantFox.
👏 Great work, @KodeSage! Keep contributing to ShadeProtocol.