Enum Error 

#[non_exhaustive]
pub enum Error {
    BadRequest(ApiError),
    Authentication(ApiError),
    PermissionDenied(ApiError),
    NotFound(ApiError),
    RequestTooLarge(ApiError),
    RateLimit {
        err: ApiError,
        retry_after: Option<Duration>,
    },
    Overloaded(ApiError),
    Api {
        status: u16,
        err: ApiError,
    },
    Timeout,
    Connection(Error),
    Serde(Error),
    Stream(String),
    Config(String),
}

All errors the SDK can return.

The per-status variants (BadRequest, Authentication, …) mirror the documented HTTP error codes; any other non-2xx status maps to Error::Api. Use Error::is_retryable to decide whether an error is worth retrying (the client already retries automatically up to max_retries).

Examples

use crimson_crab::{ApiError, Error};

let err = Error::Overloaded(ApiError {
    error_type: "overloaded_error".into(),
    message: "overloaded".into(),
    request_id: None,
});
assert!(err.is_retryable());

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

BadRequest(ApiError)

400 Bad Request — the request was malformed or invalid.

Authentication(ApiError)

401 Unauthorized — the API key is missing or invalid.

PermissionDenied(ApiError)

403 Forbidden — the key lacks permission (also billing_error).

NotFound(ApiError)

404 Not Found — the endpoint or resource does not exist.

RequestTooLarge(ApiError)

413 Payload Too Large — the request exceeds size limits.

RateLimit

429 Too Many Requests — rate limited; carries retry-after if sent.

Fields

err: ApiError

The structured error body.

retry_after: Option<Duration>

The server-suggested delay before retrying, from retry-after.

Overloaded(ApiError)

529 Overloaded — the API is temporarily overloaded.

Api

Any other non-2xx status not covered by a dedicated variant.

Fields

status: u16

The HTTP status code.

err: ApiError

The structured error body.

Timeout

The request timed out (retryable).

Connection(Error)

A transport-level failure (DNS, TCP, TLS, …).

Serde(Error)

A JSON (de)serialization failure.

Stream(String)

A streaming decode error (e.g. a malformed batch-results line).

Config(String)

A configuration error (e.g. a missing API key or invalid builder input).

Implementations

impl Error

pub fn is_retryable(&self) -> bool

Returns true if retrying the operation might succeed.

Retryable errors are rate limits, overloads, timeouts, connection failures, and 408/409/>= 500 API errors.

Examples

use crimson_crab::{ApiError, Error};

let bad = Error::BadRequest(ApiError {
    error_type: "invalid_request_error".into(),
    message: "nope".into(),
    request_id: None,
});
assert!(!bad.is_retryable());
assert!(Error::Timeout.is_retryable());

pub fn retry_after(&self) -> Option<Duration>

Returns the server-suggested retry delay, if the error carries one.

Only Error::RateLimit can carry a retry-after value.

Examples

use std::time::Duration;
use crimson_crab::{ApiError, Error};

let err = Error::RateLimit {
    err: ApiError { error_type: "rate_limit_error".into(), message: "slow".into(), request_id: None },
    retry_after: Some(Duration::from_secs(3)),
};
assert_eq!(err.retry_after(), Some(Duration::from_secs(3)));
assert_eq!(Error::Timeout.retry_after(), None);

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(err: Error) -> Self

Converts to this type from the input type.