use std::fmt;
use crate::models::{xhr_calls, XhrCall};
pub type Result<T, E = Error> = std::result::Result<T, E>;
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
#[error(
"no API key provided: pass one to Client::new or set the SCRAPEUNBLOCKER_KEY \
environment variable (get your key at https://app.scrapeunblocker.com)"
)]
MissingApiKey,
#[error(transparent)]
Api(Box<ApiError>),
#[error("request timed out: {0}")]
Timeout(#[source] reqwest::Error),
#[error("could not reach the ScrapeUnblocker API: {0}")]
Connection(#[source] reqwest::Error),
#[error("could not decode the API response: {0}")]
Decode(String),
#[error("invalid client configuration: {0}")]
Config(String),
}
impl Error {
pub fn api(&self) -> Option<&ApiError> {
match self {
Error::Api(e) => Some(e),
_ => None,
}
}
pub fn status(&self) -> Option<u16> {
self.api().map(|e| e.status)
}
}
impl From<ApiError> for Error {
fn from(e: ApiError) -> Self {
Error::Api(Box::new(e))
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum ApiErrorKind {
InvalidRequest,
Authentication,
NoSubscription,
PaymentRequired,
QuotaExceeded,
CreditLimitExceeded,
BudgetExceeded,
PaymentFailed,
Blocked,
NotFound,
TargetNotFound,
BrowserTimeout,
UnsupportedContent,
Validation,
StepFailed,
RateLimit,
UpstreamOutage,
Server,
Other,
}
impl ApiErrorKind {
pub fn is_authentication(self) -> bool {
matches!(self, Self::Authentication | Self::NoSubscription)
}
pub fn is_payment_required(self) -> bool {
matches!(
self,
Self::PaymentRequired
| Self::QuotaExceeded
| Self::CreditLimitExceeded
| Self::BudgetExceeded
| Self::PaymentFailed
)
}
pub fn is_not_found(self) -> bool {
matches!(self, Self::NotFound | Self::TargetNotFound)
}
pub fn is_validation(self) -> bool {
matches!(self, Self::Validation | Self::StepFailed)
}
}
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct ApiError {
pub kind: ApiErrorKind,
pub status: u16,
pub message: String,
pub body: Option<String>,
pub target_not_found: Option<TargetNotFound>,
pub step_failed: Option<StepFailure>,
}
impl fmt::Display for ApiError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.message)
}
}
impl std::error::Error for ApiError {}
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct TargetNotFound {
pub origin_status: u16,
pub html: Option<String>,
pub destination_url: Option<String>,
}
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct StepFailure {
pub step_index: Option<u64>,
pub action: Option<String>,
pub reason: Option<String>,
pub selector: Option<String>,
pub html: Option<String>,
pub xhr: Option<Vec<XhrCall>>,
}
pub(crate) fn api_error(
status: u16,
body: Option<String>,
origin_status: Option<&str>,
destination_url: Option<String>,
) -> ApiError {
let text = body.as_deref().unwrap_or("");
let json: Option<serde_json::Value> = serde_json::from_str(text).ok();
let field =
|name: &str| -> Option<String> { json.as_ref()?.get(name)?.as_str().map(str::to_owned) };
if matches!(status, 404 | 410) {
if let Some(origin) = origin_status {
let origin_status = origin.trim().parse().unwrap_or(status);
let html = match &json {
Some(serde_json::Value::Object(_)) => field("html"),
_ => body.clone(),
};
return ApiError {
kind: ApiErrorKind::TargetNotFound,
status,
message: format!(
"Target page does not exist (HTTP {origin_status}). This is the target's \
own answer, not a block; the call is billed."
),
body,
target_not_found: Some(TargetNotFound {
origin_status,
html,
destination_url,
}),
step_failed: None,
};
}
}
let lower = text.to_lowercase();
let kind = match status {
400 => ApiErrorKind::InvalidRequest,
401 if lower.contains("no valid subscription") => ApiErrorKind::NoSubscription,
401 => ApiErrorKind::Authentication,
402 if lower.contains("quota exceeded") => ApiErrorKind::QuotaExceeded,
402 if lower.contains("credit limit exceeded") => ApiErrorKind::CreditLimitExceeded,
402 if lower.contains("user set budget exceeded") => ApiErrorKind::BudgetExceeded,
402 if lower.contains("payment failed") => ApiErrorKind::PaymentFailed,
402 => ApiErrorKind::PaymentRequired,
403 => ApiErrorKind::Blocked,
404 => ApiErrorKind::NotFound,
408 => ApiErrorKind::BrowserTimeout,
415 => ApiErrorKind::UnsupportedContent,
422 if field("error").as_deref() == Some("step_failed") => ApiErrorKind::StepFailed,
422 => ApiErrorKind::Validation,
429 => ApiErrorKind::RateLimit,
503 => ApiErrorKind::UpstreamOutage,
500..=599 => ApiErrorKind::Server,
_ => ApiErrorKind::Other,
};
if kind == ApiErrorKind::StepFailed {
let num = |name: &str| json.as_ref()?.get(name)?.as_u64();
let step = StepFailure {
step_index: num("step_index"),
action: field("action"),
reason: field("reason"),
selector: field("selector"),
html: field("html"),
xhr: xhr_calls(json.as_ref().and_then(|j| j.get("xhr"))),
};
let message = format!(
"Browser step {} ({}) failed: {}",
step.step_index
.map_or_else(|| "?".to_owned(), |i| i.to_string()),
step.action.as_deref().unwrap_or("?"),
step.reason.as_deref().unwrap_or("unknown reason"),
);
return ApiError {
kind,
status,
message,
body,
target_not_found: None,
step_failed: Some(step),
};
}
ApiError {
kind,
status,
message: message_for(status, text),
body,
target_not_found: None,
step_failed: None,
}
}
fn message_for(status: u16, body: &str) -> String {
let base = match status {
400 => "Invalid request (bad URL, unsupported scheme, or missing API key header)",
401 => "Authentication failed - key not recognised, or account has no active plan",
402 => {
"Billing block - quota exceeded, credit limit exceeded, monthly budget limit \
reached, or a failed payment"
}
403 => "Target blocked by bot protection on every bypass path",
404 => "Requested element not found on the page",
408 => "Browser run timed out before the page was ready",
415 => "URL serves a content type this call cannot return",
422 => "Validation error - see the detail array in the response body",
429 => "Rate limited - too many concurrent requests",
503 => "Upstream origin returned a server-side outage page",
504 => "Fetch timed out upstream",
_ => "",
};
let base = if base.is_empty() {
format!("API returned HTTP {status}")
} else {
base.to_owned()
};
let snippet: String = body.trim().replace('\n', " ");
if snippet.is_empty() {
return base;
}
let short: String = snippet.chars().take(200).collect();
let ellipsis = if snippet.chars().count() > 200 {
"..."
} else {
""
};
format!("{base}: {short}{ellipsis}")
}