pub struct Error { /* private fields */ }Expand description
The error every SDK call can answer with.
Implementations§
Source§impl Error
impl Error
Sourcepub fn new(code: ErrorCode, message: impl Into<String>) -> Error
pub fn new(code: ErrorCode, message: impl Into<String>) -> Error
An error of the given category, with nothing but its message so far.
Sourcepub fn usage_with_hint(
message: impl Into<String>,
hint: impl Into<String>,
) -> Error
pub fn usage_with_hint( message: impl Into<String>, hint: impl Into<String>, ) -> Error
The call was asked for wrongly, with a word on how to ask instead.
Sourcepub fn not_found(resource: &str, identifier: impl Display) -> Error
pub fn not_found(resource: &str, identifier: impl Display) -> Error
No resource answers to identifier. It reads box not found: 42.
Sourcepub fn not_found_with_hint(
resource: &str,
identifier: impl Display,
hint: impl Into<String>,
) -> Error
pub fn not_found_with_hint( resource: &str, identifier: impl Display, hint: impl Into<String>, ) -> Error
No resource answers to identifier, with a word on where else to look.
Sourcepub fn auth(message: impl Into<String>) -> Error
pub fn auth(message: impl Into<String>) -> Error
HEY wants credentials the call did not carry, or refused the ones it did.
Sourcepub fn forbidden(message: impl Into<String>) -> Error
pub fn forbidden(message: impl Into<String>) -> Error
The credentials are good but do not reach this far.
Sourcepub fn forbidden_scope() -> Error
pub fn forbidden_scope() -> Error
The token does not carry the scope a write needs, which a fresh sign-in would fix.
Sourcepub fn rate_limit(retry_after: Option<u64>) -> Error
pub fn rate_limit(retry_after: Option<u64>) -> Error
The rate-limit error a caller raises for itself, worded the way the other SDKs word
theirs: “Rate limited”. A 429 that came back from HEY reads “rate limited - try
again later” instead — see Error::from_response.
Sourcepub fn rate_limited() -> Error
pub fn rate_limited() -> Error
The client’s own rate limiter refused a call, so nothing was sent. It shares
ErrorCode::RateLimit with a 429 from HEY and is told apart by carrying no HTTP
status; Go keeps the two apart with a sentinel instead.
Sourcepub fn circuit_open() -> Error
pub fn circuit_open() -> Error
The scope’s circuit breaker is open, so the SDK refused the call itself.
Sourcepub fn cancelled() -> Error
pub fn cancelled() -> Error
The caller dropped the future before it finished — a tokio::time::timeout that
expired, a select! that took another branch. Nobody is waiting for this error: it
is what the operation hooks are told the call ended as, so the bookkeeping every
layer keeps per operation is closed out rather than left open.
It is a ErrorCode::Network because that is what a call that never got an answer
is — and it counts against the scope’s circuit breaker like any other, since a call
the caller had to give up waiting for says the same thing about HEY as one that
timed out on its own. It is not retryable: there is nobody left to answer.
Sourcepub fn bulkhead_full() -> Error
pub fn bulkhead_full() -> Error
The scope already has as many calls in flight as its bulkhead allows.
Sourcepub fn network(source: impl Error + Send + Sync + 'static) -> Error
pub fn network(source: impl Error + Send + Sync + 'static) -> Error
No answer came at all. The transport’s own account of it is the hint. It is marked retryable because the request can be sent again, not because it never arrived: a timeout or a broken body can follow a write HEY has already made, so a resend is only safe for an operation the model calls idempotent, which is the only kind the client resends on its own.
Sourcepub fn api(status: u16, message: impl Into<String>) -> Error
pub fn api(status: u16, message: impl Into<String>) -> Error
HEY answered status with a failure no other category names.
Sourcepub fn conflict(message: impl Into<String>) -> Error
pub fn conflict(message: impl Into<String>) -> Error
The request conflicts with what HEY already holds: a time track already running.
Sourcepub fn response_too_large(limit: usize, method: &Method, path: &str) -> Error
pub fn response_too_large(limit: usize, method: &Method, path: &str) -> Error
A body the client refused to read, because reading it whole is what the caller would have gone on to do. It carries no HTTP status of its own: the answer never arrived in full, so there is nothing to report about it but the refusal.
Sourcepub fn validation(messages: &[String]) -> Error
pub fn validation(messages: &[String]) -> Error
The messages the model itself produced, joined. With none of them the error still says something: “validation error”.
Sourcepub fn ambiguous(resource: &str, matches: &[String]) -> Error
pub fn ambiguous(resource: &str, matches: &[String]) -> Error
A name that matched more than one record. Up to five matches are named in the hint; beyond that the only useful advice is to narrow the search.
Go renders the matches with %v, as Did you mean: [Alice Bob]. Here they read as
a list — Did you mean: Alice, Bob — which is what a Rust caller printing the hint
would expect.
Sourcepub fn from_std(source: impl Error + Send + Sync + 'static) -> Error
pub fn from_std(source: impl Error + Send + Sync + 'static) -> Error
Wraps an error from outside the SDK as an API error that reads the way the original did, for the callers that have to answer with this type and nothing better fits.
Sourcepub fn from_response(
status: StatusCode,
method: &Method,
headers: &HeaderMap,
body: &[u8],
) -> Error
pub fn from_response( status: StatusCode, method: &Method, headers: &HeaderMap, body: &[u8], ) -> Error
Maps a non-2xx response onto the SDK’s error vocabulary. The hint carries whatever
message the server put in the body, when it sent one, and the body itself is kept on
the error for a caller that needs more of it than a hint — see Error::body.
Sourcepub fn with_hint(self, hint: impl Into<String>) -> Error
pub fn with_hint(self, hint: impl Into<String>) -> Error
Adds a word on what to do about it, printed after the message.
Sourcepub fn with_status(self, status: u16) -> Error
pub fn with_status(self, status: u16) -> Error
Records the HTTP status the failure came with.
Sourcepub fn with_request_id(self, request_id: impl Into<String>) -> Error
pub fn with_request_id(self, request_id: impl Into<String>) -> Error
Records the X-Request-Id HEY answered with, which is how support looks a call up.
Sourcepub fn with_source(self, source: impl Error + Send + Sync + 'static) -> Error
pub fn with_source(self, source: impl Error + Send + Sync + 'static) -> Error
Keeps the error underneath this one, for std::error::Error::source.
Sourcepub fn exit_code(&self) -> i32
pub fn exit_code(&self) -> i32
The process exit status a command should end with for this error.
Sourcepub fn hint(&self) -> Option<&str>
pub fn hint(&self) -> Option<&str>
What to do about it, when there is a word to say: HEY’s own message, or when to try again.
Sourcepub fn http_status(&self) -> Option<u16>
pub fn http_status(&self) -> Option<u16>
The HTTP status the failure came with, when HEY answered at all.
Sourcepub fn is_retryable(&self) -> bool
pub fn is_retryable(&self) -> bool
Whether the call is worth sending again: a 429, a 5xx, a network failure.
Sourcepub fn request_id(&self) -> Option<&str>
pub fn request_id(&self) -> Option<&str>
The X-Request-Id HEY answered with, when it did.
Sourcepub fn is_response_too_large(&self) -> bool
pub fn is_response_too_large(&self) -> bool
The answer was longer than the client will hold in memory, whether that refusal is the error itself or sits behind the status the answer carried.
Sourcepub fn body(&self) -> Option<&[u8]>
pub fn body(&self) -> Option<&[u8]>
What HEY answered the failure with, up to MAX_ERROR_BODY_BYTES. Several
endpoints describe a refusal in the body rather than in the status alone — the
contacts a clashing write collided with, the fields a 422 objected to — and this is
where that account is kept. It is None when the answer carried no body, when the
SDK raised the error itself, and when the body was too long to read.
Sourcepub fn body_json<T: DeserializeOwned>(&self) -> Option<T>
pub fn body_json<T: DeserializeOwned>(&self) -> Option<T>
The failure body read as T, or None when there is no body or it does not read as
one.
#[derive(Deserialize)]
struct Refusal {
errors: Vec<String>,
}
if let Some(refusal) = error.body_json::<Refusal>() {
println!("{}", refusal.errors.join("; "));
}Source§impl Error
impl Error
Sourcepub fn timed_out(limit: Duration) -> Error
pub fn timed_out(limit: Duration) -> Error
The operation ran past crate::ClientBuilder::operation_timeout and was dropped
where it stood. Retryable: nothing says the next call would take as long.
Sourcepub fn pagination_capped(max_pages: usize) -> Error
pub fn pagination_capped(max_pages: usize) -> Error
A walk reached the client’s page limit with pages still to read. What was read
stands with the caller; this says it was not all of it. Raise
crate::ClientBuilder::max_pages, or read with a limit.
Trait Implementations§
Source§impl Error for Error
impl Error for Error
Source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
use the Display impl or to_string()