Errors and retries

How failed requests are reported, and which requests are retried.

Errors

Every fallible method returns synthient::Result:

pub type Result<T, E = Error> = std::result::Result<T, E>;

A request that fails with a non-success HTTP status returns Error::Api, whose ApiError holds the status, the problem detail, the request ID, and any Retry-After delay. Match on it:

use std::net::Ipv4Addr;

use synthient::{Error, StatusCode};

match client.lookup_ip(Ipv4Addr::new(8, 8, 8, 8)).await {
    Ok(info) => println!("{:?}", info.intelligence),
    Err(Error::Api(err)) if err.status == StatusCode::PAYMENT_REQUIRED => {
        eprintln!("out of lookup credits");
    }
    Err(Error::Api(err)) if err.status == StatusCode::TOO_MANY_REQUESTS => {
        match err.retry_after {
            Some(retry_after) => eprintln!("rate limited, retry after {retry_after:?}"),
            None => eprintln!("monthly request budget spent"),
        }
    }
    Err(Error::Api(err)) => {
        let message = err.detail.or(err.title).unwrap_or_default();
        let request_id = err.request_id.unwrap_or_default();
        eprintln!("request {request_id} failed: {message}");
    }
    Err(err) => eprintln!("lookup failed: {err}"),
}

See Errors for what each status means.

Error

• Matching: Error is #[non_exhaustive], so a match on it needs a wildcard arm.
• Logging: Its Display output never includes server-provided details or URLs.
• Unwrapping: source() returns the underlying error for Http and Decode.

ApiError

• Traits: ApiError implements Display and std::error::Error.
• Logging: Display writes only the status, such as api returned 402 Payment Required, so it is safe to log.
• Untrusted fields: problem_type, title, detail, errors, and request_id contain untrusted server data and may include sensitive information, so inspect them explicitly.

Retries and timeouts

Which requests are retried:

• Account and feed requests are retried on 500, 502, 503, and 504 responses, on transport errors, including a failure while reading a JSON response body, and on 429 responses that carry Retry-After.
• Billed lookups (lookup_ip, lookup_ips, and lookup_domain) are retried only on 429 responses that carry Retry-After, which the rate limiter returns before doing any work, so a lookup is never charged twice. health is retried the same way, so an unhealthy API is reported at once.
• A 429 without Retry-After means the key's monthly request budget is spent or it has too many open streams, so it is returned without a retry.
• A download's request to the storage host is not retried, and neither is a failure while reading a stream or download.
• The SDK turns off reqwest's own retries, so no request is ever resent by the transport.

How retries wait:

• Retries back off exponentially from one second, doubling up to 30 seconds, with 25% jitter either way.
• The wait is never shorter than Retry-After.
• A Retry-After longer than a minute is returned to you instead of waited out.
• When the client has a timeout, a retry whose wait would outlast it is skipped, so you get the last response or error rather than Error::Timeout.
• Set the retry count with max_retries.

By default:

• Connecting gives up after 30 seconds.
• A read that stalls for 60 seconds fails, which streams never hit because the server sends a keepalive line every 15 seconds.
• There is no overall limit, because streams and downloads are long-lived.

Set one for every operation with timeout, or drop a future to cancel it:

use std::net::Ipv4Addr;
use std::time::Duration;

use synthient::{Client, reqwest};

let http = reqwest::Client::builder()
    .connect_timeout(Duration::from_secs(10))
    .read_timeout(Duration::from_secs(30));
let client = Client::builder(std::env::var("SYNTHIENT_API_KEY")?)
    .http_client(http)
    .timeout(Duration::from_secs(10))
    .build()?;
let info = client.lookup_ip(Ipv4Addr::new(8, 8, 8, 8)).await?;
println!("{}", info.ip);