Expose response status in errors and improve examples #310
Description
Hi, first of all - thank you for this library! You've done a great job here.
We’ve built our translation management service and have already integrated it with GitHub and GitLab. We're now working on Bitbucket integration and have noticed a few areas in this library that could be improved, especially compared to other libraries.
1. Error Handling
The client internally uses the UnexpectedResponseStatusError struct, but this isn’t obvious unless you dive into the code. It would be helpful to add error handling examples to the README (especially for rate-limit errors) or even to create additional examples folder with files for it. Consider a dedicated section similar to go-github's rate limit handling. GitLab's Go client even handles retries automatically for rate-limited responses - while that might be out of scope here, it's a helpful comparison. I’ve also seen that other users have mentioned this issue here.
2. Status Code
Right now, it's not convenient to parse the error text, and it’s generally not best practice. Ideally, it's better to return the HTTP status code directly. I’d suggest adding a Status int field to the UnexpectedResponseStatusError struct. This should be simple, since the status code is already available right here.
This would make it much easier to programmatically handle specific cases like 429 (rate limit), 404, etc.
I'm happy to help contribute to this as well - it would be beneficial for our project too.