Conversation
…limit 429s - UsageSnapshot (hirebase.UsageSnapshot): parsed from the Hirebase-Usage-* / X-Billing-Code / Retry-After headers of the most recent response; available as client.last_usage on Client and AsyncClient. - QuotaExceededError: raised for 429s carrying X-Billing-Code: limit_exceeded (plan allowance used up); subclasses RateLimitError so existing handlers keep working; carries .usage. - RateLimitError now carries .retry_after and .usage. - error_from_response accepts headers; _handle_response forwards them. - README: quota tracking section and error table rows. Refs #1. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
ssr145
changed the title
Per review: usage metadata is returned with the call rather than kept as
mutable state on the client.
jobs, meta = client.jobs.search(query, limit=50, return_meta=True)
meta.usage.included_remaining
- New hirebase.ResponseMeta (status_code, lower-cased headers, request_id,
usage: UsageSnapshot | None), built by Client._request_meta /
AsyncClient._request_meta.
- return_meta on every metered jobs/companies method, sync and async.
search/get carry Literal overloads so the tuple shape type-checks.
- Default return shape unchanged; tests that stub _request keep working.
- client.last_usage removed (unreleased). QuotaExceededError.usage stays.
- README + docs updated; tests reworked (76 passed).
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #1 (items 1 and 2). Found during the 2026-09-07 metering QA pass on api-dev.
return_meta=Trueon every metered method (jobs.*andcompanies.*, sync and async). The call returns(result, meta)wheremetais a newhirebase.ResponseMetawithstatus_code, lower-casedheaders,request_id, andusage(aUsageSnapshotparsed fromHirebase-Usage-*,Noneon un-metered endpoints). Per review, this replaces the earlierclient.last_usageattribute so there is no mutable per-client state.searchandgetcarryLiteraloverloads so the tuple shape type-checks; the default return shape is unchanged.QuotaExceededError: raised for 429s that carryX-Billing-Code: limit_exceeded(block-mode plan at its cap). SubclassesRateLimitError, so existingexcept RateLimitErrorcode still works, and exposes.usage(e.g.included_remaining, which the API's reservation 429 relies on).RateLimitError.retry_afterfrom theRetry-Afterheader on the request limiter's 429.README,
docs/jobs.md,docs/companies.md,docs/errors.mdupdated.Correction to #1 item 3: the 0.1.0 string is in
hirebase_cli, nothirebase._version; left untouched here.Tests
tests/test_usage_headers.pyreworked for the per-call shape (incl. a check that mock transports stubbing_requeststill work); full offline suite 76 passed, 5 skipped.Branched from 0e8f0b5 (salary benchmark) to avoid conflicts with that work.
🤖 Generated with Claude Code