Implement unified response parser

[codebestia]

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) -> dict in http_client.py.
• On 2xx: decode JSON and return the dict.
• On 401: raise AuthenticationError.
• On 400 / 422: raise InvalidRequestError with 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 ShadeError rather than crashing with a raw JSONDecodeError.
• 2xx responses that contain an error key in the body are still treated as errors.

[ciynthia]

Hello, this issue aligns well with my skill set and I’m confident I can resolve it properly. Please assign it to me.

[KodeSage]

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]

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]

🦊 GrantFox — @KodeSage has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #12)
2. Your PR will be reviewed by the ShadeProtocol maintainers

Good luck! Track your progress on GrantFox.