:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
use axum::http::StatusCode;
use axum::response::{IntoResponse, Json, Response};
use common_cookieless::{CookielessManagerError, SaltCacheError};
use common_database::{
extract_timeout_type, is_timeout_error, is_transient_error, CustomDatabaseError,
};
use common_hypercache::HyperCacheError;
use common_redis::CustomRedisError;
use serde::Serialize;
use std::sync::Arc;
use thiserror::Error;
use crate::utils::graph_utils::DependencyType;
/// Simplifies serde error messages for end-user consumption.
///
/// Serde errors can be verbose, listing all valid enum variants, e.g.:
/// "unknown variant `contains`, expected one of `exact`, `is_not`, `icontains`, ..."
///
/// This truncates at ", expected" to produce a simpler message:
/// "unknown variant `contains`"
///
/// Full details are logged server-side; this is just for the client response.
pub fn simplify_serde_error(error: &str) -> &str {
error.split(", expected").next().unwrap_or(error)
}
/// Structured error response matching Django REST Framework's format
#[derive(Debug, Serialize)]
pub struct AuthenticationErrorResponse {
#[serde(rename = "type")]
pub error_type: String,
pub code: String,
pub detail: String,
pub attr: Option<String>,
}
#[derive(Error, Debug)]
pub enum ClientFacingError {
#[error("Invalid request: {0}")]
BadRequest(String),
#[error("Unauthorized: {0}")]
Unauthorized(String),
#[error("Rate limited")]
RateLimited,
#[error("IP rate limited")]
IpRateLimited,
#[error("Token rate limited")]
TokenRateLimited,
#[error("billing limit reached")]
BillingLimit,
#[error("Service unavailable")]
ServiceUnavailable,
}
#[derive(Error, Debug)]
pub enum FlagError {
#[error(transparent)]
ClientFacing(#[from] ClientFacingError),
/// `code` is public: it ships as `reason.code` and as a metrics label.
/// Named `cause` because thiserror would treat `source` as `#[source]`,
/// which `anyhow::Error` cannot satisfy.
#[error("{cause}")]
InternalError {
code: &'static str,
cause: anyhow::Error,
},
#[error("{cause}")]
Unavailable {
code: &'static str,
cause: anyhow::Error,
},
#[error("failed to decode request: {0}")]
RequestDecodingError(String),
#[error("Decompressed request body exceeds limit ({decompressed} > {limit} bytes)")]
PayloadTooLarge { decompressed: usize, limit: usize },
#[error("failed to parse request: {0}")]
RequestParsingError(#[from] serde_json::Error),
#[error("No distinct_id in request")]
MissingDistinctId,
#[error("No api_key in request")]
NoTokenError,
#[error("API key is not valid")]
TokenValidationError,
#[error("Personal API key is invalid")]
PersonalApiKeyInvalid,
#[error("Personal API key lacks required scopes")]
PersonalApiKeyInsufficientScopes,
#[error("Secret API token is invalid")]
SecretApiTokenInvalid,
#[error("No authentication credentials provided")]
NoAuthenticationProvided,
#[error("Row not found in postgres")]
RowNotFound,
#[error("database unavailable")]
DatabaseUnavailable,
#[error("Failed to fetch hash key override for experience continuity")]
HashKeyOverrideError,
#[error("Database error: {0}")]
DatabaseError(sqlx::Error, Option<String>),
/// Timeout error with optional type classification.
///
/// Valid timeout types include:
/// - `"query_canceled"` - Statement timeout (PostgreSQL SQLSTATE 57014)
/// - `"lock_not_available"` - Lock timeout (PostgreSQL SQLSTATE 55P03)
/// - `"idle_in_transaction_timeout"` - Idle transaction timeout (PostgreSQL SQLSTATE 25P03)
/// - `"pool_timeout"` - Connection pool acquisition timeout
/// - `"io_timeout"` - Network/socket timeout
/// - `"protocol_timeout"` - PostgreSQL protocol timeout
/// - `"client_timeout"` - Client-side tokio::timeout wrapper
/// - `"persons_db_deadline"` - Deadline shared by all persons DB work in one flag evaluation
/// - `"redis_timeout"` - Redis operation timeout
/// - `"cache_timeout"` - Cache operation timeout
/// - `"database_timeout"` - Generic database timeout (fallback when SQLSTATE unavailable)
/// - `None` - Timeout occurred but specific type unknown
#[error("Timed out while fetching data")]
TimeoutError(Option<String>),
#[error("Dependency of type {0} with id {1} not found")]
DependencyNotFound(DependencyType, i64),
#[error("Flag dependency {0} failed to evaluate")]
DependencyFailed(i64),
#[error("Group type mapping lookup failed: {0}")]
GroupTypeLookupFailed(Arc<FlagError>),
/// A failed `posthog_cohort` query, wrapping a `FlagError::internal`. Clients see what the
/// wrapped error shows them, but the request outcome counts it as a database failure.
#[error(transparent)]
CohortQueryFailed(Box<FlagError>),
#[error("Failed to parse cohort filters")]
CohortFiltersParsingError,
#[error("Dependency cycle detected: {0} id {1} starts the cycle")]
DependencyCycle(DependencyType, i64),
#[error("Rayon semaphore acquisition timed out after {0}ms")]
RayonSemaphoreTimeout(u64),
#[error(transparent)]
CookielessError(#[from] CookielessManagerError),
/// A stored remote-config payload could not be decrypted with any configured key (or no
/// decryptor is configured at all). Distinct from `Internal` so the response is JSON, not
/// plain text -- SDKs calling `remote_config` parse the body as JSON on every status code.
#[error("failed to decrypt remote config payload: {0}")]
RemoteConfigDecryptFailed(String),
}
/// Codes that more than one site compares against, so the constructor and each
/// comparison cannot drift apart. The codes used at one site only stay inline: a
/// single literal has no second reference to disagree with.
pub(crate) const CODE_FLAG_DATA_PARSING: &str = "flag_data_parsing_error";
pub(crate) const CODE_PERSON_NOT_FOUND: &str = "person_not_found";
pub(crate) const CODE_DEPENDENCY_FAILED: &str = "dependency_failed";
const TIMEOUT_CLIENT: &str = "client_timeout";
const TIMEOUT_PERSONS_DB_DEADLINE: &str = "persons_db_deadline";
impl FlagError {
/// The `Internal error: ` prefix reaches customers as the `$feature_flag_reason`
/// event property, so changing it changes their data. `context` keeps the chain.
pub fn internal(cause: impl Into<anyhow::Error>) -> Self {
let cause = cause.into();
let message = format!("Internal error: {cause}");
FlagError::InternalError {
code: "internal_error",
cause: cause.context(message),
}
}
/// Corrupt or mismatched data, so a 500 rather than a retryable 503.
pub fn flag_data_parsing(details: impl std::fmt::Display) -> Self {
FlagError::InternalError {
code: CODE_FLAG_DATA_PARSING,
cause: anyhow::anyhow!("Failed to parse flag data: {details}"),
}
}
pub fn data_parsing(cause: impl Into<anyhow::Error>) -> Self {
FlagError::InternalError {
code: "data_parsing_error",
cause: cause.into().context("Failed to parse data"),
}
}
pub fn flag_evaluation(details: impl std::fmt::Debug) -> Self {
FlagError::InternalError {
code: "flag_evaluation_error",
cause: anyhow::anyhow!("Flag evaluation failed: {details:?}"),
}
}
pub fn batch_evaluation_panicked() -> Self {
FlagError::InternalError {
code: "batch_evaluation_panicked",
cause: anyhow::anyhow!("Parallel batch evaluation task panicked"),
}
}
pub fn redis_unavailable(cause: impl Into<anyhow::Error>) -> Self {
FlagError::Unavailable {
code: "redis_unavailable",
cause: cause.into().context("redis unavailable"),
}
}
pub fn cache_miss() -> Self {
FlagError::Unavailable {
code: "cache_miss",
cause: anyhow::anyhow!("Cache miss - data not found in cache"),
}
}
pub fn person_not_found() -> Self {
FlagError::Unavailable {
code: CODE_PERSON_NOT_FOUND,
cause: anyhow::anyhow!("Person not found"),
}
}
pub fn client_timeout() -> Self {
FlagError::TimeoutError(Some(TIMEOUT_CLIENT.to_string()))
}
pub fn persons_db_deadline() -> Self {
FlagError::TimeoutError(Some(TIMEOUT_PERSONS_DB_DEADLINE.to_string()))
}
pub fn is_persons_db_deadline(&self) -> bool {
matches!(self, FlagError::TimeoutError(Some(t)) if t == TIMEOUT_PERSONS_DB_DEADLINE)
}
/// Returns (error_code, status_code) for this error.
///
/// This consolidates error classification in one place to ensure consistency
/// between error codes and HTTP status codes, and makes adding new error
/// variants easier (only one match statement to update).
fn error_metadata(&self) -> (&'static str, u16) {
match self {
// Client-facing errors
FlagError::ClientFacing(ClientFacingError::BadRequest(_)) => ("bad_request", 400),
FlagError::ClientFacing(ClientFacingError::Unauthorized(_)) => ("unauthorized", 401),
FlagError::ClientFacing(ClientFacingError::RateLimited) => ("rate_limited", 429),
FlagError::ClientFacing(ClientFacingError::IpRateLimited) => ("ip_rate_limited", 429),
FlagError::ClientFacing(ClientFacingError::TokenRateLimited) => {
("token_rate_limited", 429)
}
FlagError::ClientFacing(ClientFacingError::BillingLimit) => ("billing_limit", 402),
FlagError::ClientFacing(ClientFacingError::ServiceUnavailable) => {
("service_unavailable", 503)
}
// Request parsing errors (400)
FlagError::RequestDecodingError(_) => ("request_decoding_error", 400),
FlagError::RequestParsingError(_) => ("request_parsing_error", 400),
FlagError::MissingDistinctId => ("missing_distinct_id", 400),
FlagError::PayloadTooLarge { .. } => ("payload_too_large", 413),
// Authentication errors (401)
FlagError::NoTokenError => ("missing_token", 401),
FlagError::TokenValidationError => ("invalid_token", 401),
FlagError::PersonalApiKeyInvalid => ("personal_api_key_invalid", 401),
FlagError::PersonalApiKeyInsufficientScopes => {
("personal_api_key_insufficient_scopes", 403)
}
FlagError::SecretApiTokenInvalid => ("secret_api_token_invalid", 401),
FlagError::NoAuthenticationProvided => ("no_authentication", 401),
// Bucketed errors carry their own stable code.
FlagError::InternalError { code, .. } => (code, 500),
FlagError::Unavailable { code, .. } => (code, 503),
// Internal server errors (500)
FlagError::DatabaseError(_, _) => ("database_error", 500),
FlagError::RowNotFound => ("row_not_found", 500),
FlagError::DependencyNotFound(_, _) => ("dependency_not_found", 500),
FlagError::DependencyFailed(_) => (CODE_DEPENDENCY_FAILED, 500),
FlagError::GroupTypeLookupFailed(cause) => cause.error_metadata(),
FlagError::CohortQueryFailed(cause) => cause.error_metadata(),
FlagError::CohortFiltersParsingError => ("cohort_filters_parsing_error", 500),
FlagError::DependencyCycle(_, _) => ("dependency_cycle", 500),
FlagError::HashKeyOverrideError => ("hash_key_override_error", 500),
FlagError::RayonSemaphoreTimeout(_) => ("rayon_semaphore_timeout", 504),
FlagError::RemoteConfigDecryptFailed(_) => ("remote_config_decrypt_failed", 500),
// Service unavailable errors (503) - transient issues, retry may help
FlagError::DatabaseUnavailable => ("database_unavailable", 503),
FlagError::TimeoutError(_) => ("timeout", 503),
// Cookieless errors (mixed)
FlagError::CookielessError(err) => match err {
CookielessManagerError::MissingProperty(_)
| CookielessManagerError::UrlParseError(_)
| CookielessManagerError::InvalidTimestamp(_)
| CookielessManagerError::SaltCacheError(SaltCacheError::DateOutOfRange) => {
("cookieless_error", 400)
}
_ => ("cookieless_error", 500),
},
}
}
/// Whether this error definitively means the token does not map to any team.
/// Transient infrastructure errors (timeouts, Redis/DB unavailable) return false
/// to avoid poisoning the negative cache with valid tokens during outages.
pub fn is_token_not_found(&self) -> bool {
matches!(
self,
FlagError::TokenValidationError | FlagError::RowNotFound
)
}
/// Returns a short error code for canonical logging.
pub fn error_code(&self) -> &'static str {
self.error_metadata().0
}
/// Returns the HTTP status code for this error.
pub fn status_code(&self) -> u16 {
self.error_metadata().1
}
/// Returns a granular error code for flag evaluation failures.
/// This provides more specific error classification than `error_code()`,
/// particularly for database errors where we can distinguish between
/// timeouts, connection pool exhaustion, etc.
/// Falls back to `error_code()` for variants that don't need extra granularity.
pub fn evaluation_error_code(&self) -> String {
match self {
FlagError::DatabaseError(sqlx_error, context) => {
let error_msg = sqlx_error.to_string();
let context_msg = context.as_deref().unwrap_or("");
if error_msg.contains("statement timeout") {
"timeout".to_string()
} else if error_msg.contains("no more connections") {
"no_more_connections".to_string()
} else if context_msg.contains("Failed to fetch conditions") {
"flag_condition_retry".to_string()
} else if context_msg.contains("Failed to fetch group") {
"group_mapping_retry".to_string()
} else if context_msg.contains("Database healthcheck failed") {
"healthcheck_failed".to_string()
} else if error_msg.contains("query_wait_timeout") {
"query_wait_timeout".to_string()
} else {
self.error_code().to_string()
}
}
FlagError::TimeoutError(Some(t)) => format!("timeout:{t}"),
FlagError::TimeoutError(None) => "timeout_error".to_string(),
FlagError::GroupTypeLookupFailed(cause) => cause.evaluation_error_code(),
FlagError::DependencyNotFound(dependency_type, _) => match dependency_type {
DependencyType::Cohort => "dependency_not_found_cohort".to_string(),
DependencyType::Flag => "dependency_not_found_flag".to_string(),
},
FlagError::DependencyCycle(dependency_type, _) => match dependency_type {
DependencyType::Cohort => "dependency_cycle_cohort".to_string(),
DependencyType::Flag => "dependency_cycle_flag".to_string(),
},
_ => self.error_code().to_string(),
}
}
/// Returns a human-readable description for flag evaluation failures.
/// Provides detailed descriptions for variants where the `Display` impl
/// is too technical, and falls back to `to_string()` (the `#[error]` message)
/// for everything else.
pub fn evaluation_error_description(&self) -> String {
match self {
FlagError::DatabaseError(sqlx_error, context) => {
let error_msg = sqlx_error.to_string();
let context_msg = context.as_deref().unwrap_or("");
if error_msg.contains("statement timeout") {
"Database statement timed out".to_string()
} else if error_msg.contains("no more connections") {
"Database connection pool exhausted".to_string()
} else if context_msg.contains("Failed to fetch conditions") {
"Failed to fetch flag conditions".to_string()
} else if context_msg.contains("Failed to fetch group") {
"Failed to fetch group mappings".to_string()
} else if context_msg.contains("Database healthcheck failed") {
"Database healthcheck failed".to_string()
} else if error_msg.contains("query_wait_timeout") {
"Query wait timeout exceeded".to_string()
} else {
"Database connection error during evaluation".to_string()
}
}
FlagError::TimeoutError(Some(t)) => format!("Timeout: {t}"),
FlagError::DependencyNotFound(dependency_type, _) => match dependency_type {
DependencyType::Cohort => "Cohort dependency not found".to_string(),
DependencyType::Flag => "Flag dependency not found".to_string(),
},
FlagError::DependencyFailed(_) => "Flag dependency failed to evaluate".to_string(),
FlagError::GroupTypeLookupFailed(cause) => cause.evaluation_error_description(),
FlagError::DependencyCycle(dependency_type, _) => match dependency_type {
DependencyType::Cohort => "Cohort dependency cycle detected".to_string(),
DependencyType::Flag => "Flag dependency cycle detected".to_string(),
},
_ => self.to_string(),
}
}
pub fn is_5xx(&self) -> bool {
self.status_code() >= 500
}
/// A flag failure caused by a database or a timeout, not by the flag's configuration.
/// `DependencyFailed` is excluded, because the flag it depends on carries the cause.
pub fn is_database_or_timeout_failure(&self) -> bool {
match self {
FlagError::DatabaseError(..)
| FlagError::DatabaseUnavailable
| FlagError::TimeoutError(_)
| FlagError::HashKeyOverrideError
| FlagError::CohortQueryFailed(_)
// The lookup reports a failed query, a statement timeout included, as an internal error.
| FlagError::GroupTypeLookupFailed(_) => true,
FlagError::ClientFacing(_)
| FlagError::InternalError { .. }
| FlagError::Unavailable { .. }
| FlagError::RequestDecodingError(_)
| FlagError::PayloadTooLarge { .. }
| FlagError::RequestParsingError(_)
| FlagError::MissingDistinctId
| FlagError::NoTokenError
| FlagError::TokenValidationError
| FlagError::PersonalApiKeyInvalid
| FlagError::PersonalApiKeyInsufficientScopes
| FlagError::SecretApiTokenInvalid
| FlagError::NoAuthenticationProvided
| FlagError::RowNotFound
| FlagError::DependencyNotFound(..)
| FlagError::DependencyFailed(_)
| FlagError::CohortFiltersParsingError
| FlagError::DependencyCycle(..)
| FlagError::RayonSemaphoreTimeout(_)
| FlagError::CookielessError(_)
| FlagError::RemoteConfigDecryptFailed(_) => false,
}
}
}
impl IntoResponse for FlagError {
fn into_response(self) -> Response {
match self {
FlagError::ClientFacing(err) => match err {
ClientFacingError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg),
ClientFacingError::Unauthorized(msg) => (StatusCode::UNAUTHORIZED, msg),
ClientFacingError::BillingLimit => {
let response = AuthenticationErrorResponse {
error_type: "quota_limited".to_string(),
code: "payment_required".to_string(),
detail: "You have exceeded your feature flag request quota".to_string(),
attr: None,
};
return (StatusCode::PAYMENT_REQUIRED, Json(response)).into_response();
}
ClientFacingError::RateLimited
| ClientFacingError::IpRateLimited
| ClientFacingError::TokenRateLimited => {
let response = AuthenticationErrorResponse {
error_type: "validation_error".to_string(),
code: "rate_limit_exceeded".to_string(),
detail: "Rate limit exceeded".to_string(),
attr: None,
};
return (StatusCode::TOO_MANY_REQUESTS, Json(response)).into_response();
}
ClientFacingError::ServiceUnavailable => (StatusCode::SERVICE_UNAVAILABLE, "Service is currently unavailable. Please try again later.".to_string()),
},
FlagError::InternalError { code, cause } => {
tracing::error!(error_code = code, "Internal server error: {cause:?}");
// Corrupt flag data will fail every retry, so this one names the
// thing the customer can actually fix.
let detail = if code == CODE_FLAG_DATA_PARSING {
"Failed to parse flag configuration data. This may indicate a misconfigured feature flag. Please check your flag definitions or contact support."
} else {
"An internal server error occurred. Please try again later or contact support if the problem persists."
};
(StatusCode::INTERNAL_SERVER_ERROR, detail.to_string())
}
FlagError::Unavailable { code, cause } => {
match code {
// A person row that has not landed yet is expected under
// replication lag, so it does not deserve an error line.
CODE_PERSON_NOT_FOUND => tracing::warn!(
error_code = code,
"Service dependency unavailable: {cause:?}"
),
_ => tracing::error!(
error_code = code,
"Service dependency unavailable: {cause:?}"
),
}
(
StatusCode::SERVICE_UNAVAILABLE,
"A service dependency is temporarily unavailable. This is likely a temporary issue. Please try again later.".to_string(),
)
}
FlagError::RequestDecodingError(msg) => {
(StatusCode::BAD_REQUEST, format!("Failed to decode request: {msg}. Please check your request format and try again."))
}
FlagError::PayloadTooLarge { decompressed, limit } => {
tracing::warn!(decompressed, limit, "Decompressed request body exceeded cap");
(
StatusCode::PAYLOAD_TOO_LARGE,
format!(
"Decompressed request body exceeded {limit} bytes (got {decompressed}). \
If this is a legitimate workload, contact PostHog support."
),
)
}
FlagError::RequestParsingError(err) => {
(StatusCode::BAD_REQUEST, format!("Failed to parse request: {err}. Please ensure your request is properly formatted and all required fields are present."))
}
FlagError::MissingDistinctId => {
(StatusCode::BAD_REQUEST, "The distinct_id field is missing from the request. Please include a valid identifier.".to_string())
}
FlagError::NoTokenError => {
let response = AuthenticationErrorResponse {
error_type: "authentication_error".to_string(),
code: "not_authenticated".to_string(),
detail: "No API token provided. Please include a valid API token in your request.".to_string(),
attr: None,
};
return (StatusCode::UNAUTHORIZED, Json(response)).into_response();
}
FlagError::TokenValidationError => {
let response = AuthenticationErrorResponse {
error_type: "authentication_error".to_string(),
code: "authentication_failed".to_string(),
detail: "The provided API key is invalid or has expired. Please check your API key and try again.".to_string(),
attr: None,
};
return (StatusCode::UNAUTHORIZED, Json(response)).into_response();
}
FlagError::PersonalApiKeyInvalid => {
let response = AuthenticationErrorResponse {
error_type: "authentication_error".to_string(),
code: "authentication_failed".to_string(),
detail: "Personal API key is invalid.".to_string(),
attr: None,
};
return (StatusCode::UNAUTHORIZED, Json(response)).into_response();
}
FlagError::PersonalApiKeyInsufficientScopes => {
let response = AuthenticationErrorResponse {
error_type: "authentication_error".to_string(),
code: "permission_denied".to_string(),
detail: "Personal API key lacks required scopes (feature_flag:read or feature_flag:write).".to_string(),
attr: None,
};
return (StatusCode::FORBIDDEN, Json(response)).into_response();
}
FlagError::SecretApiTokenInvalid => {
let response = AuthenticationErrorResponse {
error_type: "authentication_error".to_string(),
code: "authentication_failed".to_string(),
detail: "Secret API token is invalid.".to_string(),
attr: None,
};
return (StatusCode::UNAUTHORIZED, Json(response)).into_response();
}
FlagError::NoAuthenticationProvided => {
let response = AuthenticationErrorResponse {
error_type: "authentication_error".to_string(),
code: "not_authenticated".to_string(),
detail: "Authentication credentials were not provided.".to_string(),
attr: None,
};
return (StatusCode::UNAUTHORIZED, Json(response)).into_response();
}
FlagError::DatabaseUnavailable => {
tracing::error!("Database unavailable: {:?}", self);
(
StatusCode::SERVICE_UNAVAILABLE,
"Our database service is currently unavailable. This is likely a temporary issue. Please try again later.".to_string(),
)
}
FlagError::DatabaseError(sqlx_error, context) => {
if let Some(ctx) = context {
tracing::error!("Database error with context '{}': {}", ctx, sqlx_error);
} else {
tracing::error!("Database error: {}", sqlx_error);
}
(
StatusCode::INTERNAL_SERVER_ERROR,
"A database error occurred. Please try again later or contact support if the problem persists.".to_string(),
)
}
FlagError::TimeoutError(ref timeout_type) => {
let timeout_desc = timeout_type.as_deref().unwrap_or("unknown type");
tracing::error!("Timeout error ({}): {:?}", timeout_desc, self);
(
StatusCode::SERVICE_UNAVAILABLE,
"The request timed out. This could be due to high load or network issues. Please try again later.".to_string(),
)
}
FlagError::RowNotFound => {
tracing::error!("Row not found in postgres: {:?}", self);
(
StatusCode::INTERNAL_SERVER_ERROR,
"The requested row was not found in the database. Please try again later or contact support if the problem persists.".to_string(),
)
}
FlagError::DependencyNotFound(dependency_type, dependency_id) => {
tracing::error!("Dependency of type {dependency_type} with id {dependency_id} not found");
(StatusCode::INTERNAL_SERVER_ERROR, format!("Dependency of type {dependency_type} with id {dependency_id} not found"))
}
FlagError::DependencyFailed(dependency_id) => {
tracing::error!("Flag dependency {dependency_id} failed to evaluate");
(StatusCode::INTERNAL_SERVER_ERROR, format!("Flag dependency {dependency_id} failed to evaluate"))
}
FlagError::GroupTypeLookupFailed(cause) => {
tracing::error!("Group type mapping lookup failed: {cause:?}");
(
StatusCode::from_u16(cause.status_code())
.unwrap_or(StatusCode::INTERNAL_SERVER_ERROR),
"Group type mapping lookup failed".to_string(),
)
}
FlagError::CohortQueryFailed(cause) => return cause.into_response(),
FlagError::CohortFiltersParsingError => {
tracing::error!("Failed to parse cohort filters: {:?}", self);
(StatusCode::INTERNAL_SERVER_ERROR, "Failed to parse cohort filters. Please try again later or contact support if the problem persists.".to_string())
}
FlagError::DependencyCycle(dependency_type, cycle_start_id) => {
tracing::error!("{} dependency cycle: {:?}", dependency_type, cycle_start_id);
(StatusCode::INTERNAL_SERVER_ERROR, format!("Dependency cycle detected: {dependency_type} id {cycle_start_id} starts the cycle"))
}
FlagError::HashKeyOverrideError => {
tracing::error!("Failed to fetch hash key override for experience continuity");
(StatusCode::INTERNAL_SERVER_ERROR, "Failed to fetch hash key override for experience continuity. Please try again later.".to_string())
}
FlagError::RayonSemaphoreTimeout(ms) => {
tracing::warn!("Rayon semaphore acquisition timed out after {}ms", ms);
(StatusCode::GATEWAY_TIMEOUT, format!("Evaluation pool busy, timed out after {ms}ms. Please retry."))
}
FlagError::RemoteConfigDecryptFailed(_) => {
// The failure is already logged with project_id/flag_key context at the source in
// resolve_decrypted_payload; don't log it a second time here.
let response = AuthenticationErrorResponse {
error_type: "server_error".to_string(),
code: "remote_config_decrypt_failed".to_string(),
detail: "Failed to decrypt the remote config payload. Please contact support if the problem persists.".to_string(),
attr: None,
};
return (StatusCode::INTERNAL_SERVER_ERROR, Json(response)).into_response();
}
FlagError::CookielessError(err) => {
match err {
// 400 Bad Request errors - client-side issues
CookielessManagerError::MissingProperty(prop) => {
tracing::warn!("Cookieless missing property: {}", prop);
(StatusCode::BAD_REQUEST, format!("Missing required property: {prop}"))
},
CookielessManagerError::UrlParseError(e) => {
tracing::warn!("Cookieless URL parse error: {}", e);
(StatusCode::BAD_REQUEST, format!("Invalid URL: {e}"))
},
CookielessManagerError::InvalidTimestamp(msg) => {
tracing::warn!("Cookieless invalid timestamp: {}", msg);
(StatusCode::BAD_REQUEST, format!("Invalid timestamp: {msg}"))
},
// sent_at resolved to a date outside the salt-cache validity window
// (e.g. crawlers with frozen Date.now()) — bad input, not a server fault.
CookielessManagerError::SaltCacheError(SaltCacheError::DateOutOfRange) => {
tracing::warn!("Cookieless date out of range - sent_at outside salt-cache validity window");
(
StatusCode::BAD_REQUEST,
"Invalid sent_at: timestamp resolves to a date outside the accepted ingestion window".to_string(),
)
},
// 500 Internal Server Error - server-side issues
err @ (CookielessManagerError::HashError(_) |
CookielessManagerError::ChronoError(_) |
CookielessManagerError::RedisError(_, _) |
CookielessManagerError::SaltCacheError(_) |
CookielessManagerError::InvalidIdentifyCount(_)) => {
tracing::error!("Internal cookieless error: {}", err);
(StatusCode::INTERNAL_SERVER_ERROR, "An internal error occurred while processing your request.".to_string())
}
}
}
}
.into_response()
}
}
impl From<common_compression::CompressionError> for FlagError {
fn from(e: common_compression::CompressionError) -> Self {
match e {
common_compression::CompressionError::OutputTooLarge {
decompressed,
limit,
} => FlagError::PayloadTooLarge {
decompressed,
limit,
},
other => FlagError::RequestDecodingError(other.to_string()),
}
}
}
impl From<CustomRedisError> for FlagError {
fn from(e: CustomRedisError) -> Self {
match e {
CustomRedisError::NotFound => FlagError::TokenValidationError,
CustomRedisError::ParseError(details) => FlagError::flag_data_parsing(format!(
"Redis data parsing failed: {}",
simplify_serde_error(&details)
)),
CustomRedisError::Timeout => FlagError::TimeoutError(Some("Redis timeout".to_string())),
e @ (CustomRedisError::InvalidConfiguration(_) | CustomRedisError::Redis(_)) => {
FlagError::redis_unavailable(e)
}
}
}
}
impl From<CustomDatabaseError> for FlagError {
fn from(e: CustomDatabaseError) -> Self {
match e {
CustomDatabaseError::Timeout(_) => FlagError::client_timeout(),
CustomDatabaseError::Other(sqlx_error) => {
// Check if it's a timeout-related SQL error
if is_timeout_error(&sqlx_error) {
FlagError::TimeoutError(
extract_timeout_type(&sqlx_error).map(|s| s.to_string()),
)
} else {
FlagError::DatabaseUnavailable
}
}
}
}
}
impl From<sqlx::Error> for FlagError {
fn from(e: sqlx::Error) -> Self {
match e {
sqlx::Error::RowNotFound => FlagError::RowNotFound,
_ => {
if is_timeout_error(&e) {
// Timeouts get their own retryable classification (503) with a type tag.
FlagError::TimeoutError(extract_timeout_type(&e).map(|s| s.to_string()))
} else if is_transient_error(&e) {
// Connection resets, serialization failures, and other transient
// connection-level Postgres faults are retryable, so surface them as a
// 503 rather than treating a DB blip as a hard 500 SDKs won't retry.
//
// DatabaseUnavailable carries no payload, so log the cause here or the
// SQLSTATE is lost — that detail is what distinguishes a connection
// blip (08***) from resource exhaustion (53***) during an incident.
tracing::warn!(
sqlstate = e.as_database_error().and_then(|db| db.code()).as_deref(),
"Transient database error, returning 503: {}",
e
);
FlagError::DatabaseUnavailable
} else {
// Genuine internal faults (data corruption, unknown SQLSTATEs) stay 500.
FlagError::DatabaseError(e, None)
}
}
}
}
}
impl From<HyperCacheError> for FlagError {
fn from(e: HyperCacheError) -> Self {
match e {
HyperCacheError::CacheMiss => FlagError::cache_miss(),
HyperCacheError::Redis(redis_error) => FlagError::from(redis_error),
HyperCacheError::S3(_) => FlagError::cache_miss(),
e @ (HyperCacheError::Json(_) | HyperCacheError::Pickle(_)) => {
FlagError::data_parsing(e)
}
HyperCacheError::Timeout(_) => {
FlagError::TimeoutError(Some("cache_timeout".to_string()))
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use rstest::rstest;
use tokio::time::{timeout, Duration};
/// These strings reach customers as the `$feature_flag_reason` event property.
#[rstest]
#[case(FlagError::internal(anyhow::anyhow!("boom")), "Internal error: boom")]
#[case(
FlagError::flag_data_parsing("bad json"),
"Failed to parse flag data: bad json"
)]
#[case(
FlagError::data_parsing(anyhow::anyhow!("bad payload")),
"Failed to parse data"
)]
#[case(
FlagError::batch_evaluation_panicked(),
"Parallel batch evaluation task panicked"
)]
#[case(
FlagError::redis_unavailable(anyhow::anyhow!("connection refused")),
"redis unavailable"
)]
#[case(FlagError::cache_miss(), "Cache miss - data not found in cache")]
#[case(FlagError::person_not_found(), "Person not found")]
fn test_bucketed_error_descriptions_are_stable(
#[case] error: FlagError,
#[case] expected: &str,
) {
assert_eq!(error.evaluation_error_description(), expected);
}
#[test]
fn test_is_5xx() {
// Test 5XX errors
assert!(FlagError::internal(anyhow::anyhow!("test")).is_5xx());
assert!(FlagError::DatabaseUnavailable.is_5xx());
assert!(FlagError::redis_unavailable(anyhow::anyhow!("connection refused")).is_5xx());
assert!(FlagError::TimeoutError(None).is_5xx());
assert!(FlagError::batch_evaluation_panicked().is_5xx());
assert!(FlagError::RayonSemaphoreTimeout(800).is_5xx());
assert!(FlagError::ClientFacing(ClientFacingError::ServiceUnavailable).is_5xx());
// Test 4XX errors
assert!(
!FlagError::ClientFacing(ClientFacingError::BadRequest("test".to_string())).is_5xx()
);
assert!(
!FlagError::ClientFacing(ClientFacingError::Unauthorized("test".to_string())).is_5xx()
);
assert!(!FlagError::ClientFacing(ClientFacingError::RateLimited).is_5xx());
assert!(!FlagError::ClientFacing(ClientFacingError::BillingLimit).is_5xx());
assert!(!FlagError::MissingDistinctId.is_5xx());
assert!(!FlagError::NoTokenError.is_5xx());
assert!(!FlagError::TokenValidationError.is_5xx());
// Cookieless: DateOutOfRange is client-data (4xx); other SaltCache errors are server faults (5xx).
let salt_cache_cases = [
(SaltCacheError::DateOutOfRange, false),
(SaltCacheError::SaltRetrievalFailed, true),
(SaltCacheError::RedisError("boom".to_string()), true),
];
for (variant, expected_5xx) in salt_cache_cases {
let err = FlagError::CookielessError(CookielessManagerError::SaltCacheError(variant));
assert_eq!(err.is_5xx(), expected_5xx, "is_5xx() mismatch for {err:?}");
}
}
#[rstest]
#[case::database_error(FlagError::DatabaseError(sqlx::Error::PoolClosed, None), true)]
#[case::database_unavailable(FlagError::DatabaseUnavailable, true)]
#[case::pool_timeout(FlagError::TimeoutError(Some("pool_timeout".to_string())), true)]
#[case::persons_db_deadline(FlagError::persons_db_deadline(), true)]
#[case::hash_key_override(FlagError::HashKeyOverrideError, true)]
#[case::group_type_query_failed(
FlagError::GroupTypeLookupFailed(Arc::new(FlagError::internal(anyhow::anyhow!(
"canceling statement due to statement timeout"
)))),
true
)]
#[case::deleted_cohort(FlagError::DependencyNotFound(DependencyType::Cohort, 1), false)]
#[case::failed_flag_dependency(FlagError::DependencyFailed(1), false)]
#[case::dependency_cycle(FlagError::DependencyCycle(DependencyType::Flag, 1), false)]
#[case::unsupported_filters(FlagError::flag_data_parsing("unsupported format"), false)]
#[case::cohort_filters(FlagError::CohortFiltersParsingError, false)]
fn test_is_database_or_timeout_failure(#[case] error: FlagError, #[case] expected: bool) {
assert_eq!(error.is_database_or_timeout_failure(), expected);
}
#[test]
fn test_date_out_of_range_is_400() {
// is_5xx() for this variant is covered by the SaltCacheError table in test_is_5xx.
let err = FlagError::CookielessError(CookielessManagerError::SaltCacheError(
SaltCacheError::DateOutOfRange,
));
assert_eq!(err.status_code(), 400);
assert_eq!(err.error_code(), "cookieless_error");
}
#[test]
fn test_date_out_of_range_response_body() {
let rt = tokio::runtime::Runtime::new().unwrap();
let err = FlagError::CookielessError(CookielessManagerError::SaltCacheError(
SaltCacheError::DateOutOfRange,
));
let response = err.into_response();
assert_eq!(response.status(), StatusCode::BAD_REQUEST);
let body_bytes = rt
.block_on(axum::body::to_bytes(response.into_body(), usize::MAX))
.unwrap();
let body = String::from_utf8(body_bytes.to_vec()).unwrap();
assert!(
body.contains("Invalid sent_at"),
"body should describe the bad sent_at, got: {body}"
);
}
fn response_body(error: FlagError) -> (StatusCode, String) {
let rt = tokio::runtime::Runtime::new().unwrap();
let response = error.into_response();
let status = response.status();
let bytes = rt
.block_on(axum::body::to_bytes(response.into_body(), usize::MAX))
.unwrap();
(status, String::from_utf8(bytes.to_vec()).unwrap())
}
/// Every bucketed code renders one of three bodies. A corrupt flag definition
/// fails each retry, so it gets guidance the other two cannot give; the rest
/// share a body, which is the wording that replaced their per-variant text.
#[rstest]
#[case(
FlagError::flag_data_parsing("bad json"),
StatusCode::INTERNAL_SERVER_ERROR,
"check your flag definitions"
)]
#[case(
FlagError::data_parsing(anyhow::anyhow!("bad payload")),
StatusCode::INTERNAL_SERVER_ERROR,
"An internal server error occurred"
)]
#[case(
FlagError::batch_evaluation_panicked(),
StatusCode::INTERNAL_SERVER_ERROR,
"An internal server error occurred"
)]
#[case(
FlagError::internal(anyhow::anyhow!("boom")),
StatusCode::INTERNAL_SERVER_ERROR,
"An internal server error occurred"
)]
#[case(
FlagError::redis_unavailable(anyhow::anyhow!("connection refused")),
StatusCode::SERVICE_UNAVAILABLE,
"A service dependency is temporarily unavailable"
)]
#[case(
FlagError::cache_miss(),
StatusCode::SERVICE_UNAVAILABLE,
"A service dependency is temporarily unavailable"
)]
#[case(
FlagError::person_not_found(),
StatusCode::SERVICE_UNAVAILABLE,
"A service dependency is temporarily unavailable"
)]
fn test_bucketed_response_bodies(
#[case] error: FlagError,
#[case] expected_status: StatusCode,
#[case] expected_body: &str,
) {
let (status, body) = response_body(error);
assert_eq!(status, expected_status);
assert!(
body.contains(expected_body),
"expected body to contain {expected_body:?}, got: {body}"
);
}
/// `IntoResponse` picks the log level by comparing `code`, which the compiler
/// cannot check. A drift here would silently bury a Redis outage at warn.
#[rstest]
#[case(FlagError::redis_unavailable(anyhow::anyhow!("refused")), "ERROR")]
#[case(FlagError::cache_miss(), "ERROR")]
#[case(FlagError::person_not_found(), "WARN")]
#[case(FlagError::internal(anyhow::anyhow!("boom")), "ERROR")]
fn test_bucketed_log_levels(#[case] error: FlagError, #[case] expected_level: &str) {
#[derive(Clone, Default)]
struct Capture(std::sync::Arc<std::sync::Mutex<Vec<u8>>>);
impl std::io::Write for Capture {
fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
self.0.lock().unwrap().extend_from_slice(buf);
Ok(buf.len())
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
impl<'a> tracing_subscriber::fmt::MakeWriter<'a> for Capture {
type Writer = Self;
fn make_writer(&'a self) -> Self::Writer {
self.clone()
}
}
let writer = Capture::default();
let subscriber = tracing_subscriber::fmt()
.json()
.with_writer(writer.clone())
.with_max_level(tracing::Level::INFO)
.finish();
tracing::subscriber::with_default(subscriber, || {
drop(error.into_response());
});
let logs = String::from_utf8(writer.0.lock().unwrap().clone()).unwrap();
assert!(
logs.contains(&format!("\"level\":\"{expected_level}\"")),
"expected a {expected_level} line, got: {logs}"
);
}
#[test]
fn test_remote_config_decrypt_failed_response_is_json() {
// The remote_config response body must be JSON on every status code, because SDKs call
// res.json() on it unconditionally, so a plain-text 500 would crash them client-side.
let rt = tokio::runtime::Runtime::new().unwrap();
let err = FlagError::RemoteConfigDecryptFailed("failed to decrypt payload".to_string());
let response = err.into_response();
assert_eq!(response.status(), StatusCode::INTERNAL_SERVER_ERROR);
assert_eq!(
response
.headers()
.get("content-type")
.and_then(|v| v.to_str().ok()),
Some("application/json")
);
let body_bytes = rt
.block_on(axum::body::to_bytes(response.into_body(), usize::MAX))
.unwrap();
let body: serde_json::Value = serde_json::from_slice(&body_bytes).unwrap();
assert_eq!(body["code"], "remote_config_decrypt_failed");
}
#[test]
fn test_custom_database_error_conversion_timeout() {
// Test that CustomDatabaseError::Timeout converts to FlagError::TimeoutError with client_timeout
let rt = tokio::runtime::Runtime::new().unwrap();
let elapsed_error = rt.block_on(async {
timeout(
Duration::from_nanos(1),
tokio::time::sleep(Duration::from_secs(1)),
)
.await
.unwrap_err()
});
let timeout_error = CustomDatabaseError::Timeout(elapsed_error);
let flag_error: FlagError = timeout_error.into();
assert!(
matches!(flag_error, FlagError::TimeoutError(Some(ref timeout_type)) if timeout_type == "client_timeout")
);
}
#[test]
fn test_custom_database_error_conversion_sqlx_timeout() {
// Test that sqlx timeout errors convert to FlagError::TimeoutError with pool_timeout
let sqlx_timeout = CustomDatabaseError::Other(sqlx::Error::PoolTimedOut);
let flag_error: FlagError = sqlx_timeout.into();
assert!(
matches!(flag_error, FlagError::TimeoutError(Some(ref timeout_type)) if timeout_type == "pool_timeout")
);
}
#[test]
fn test_custom_database_error_conversion_sqlx_non_timeout() {
// Test that non-timeout sqlx errors convert to FlagError::DatabaseUnavailable
let sqlx_error = CustomDatabaseError::Other(sqlx::Error::RowNotFound);
let flag_error: FlagError = sqlx_error.into();
assert!(matches!(flag_error, FlagError::DatabaseUnavailable));
}
#[test]
fn test_direct_sqlx_timeout_conversion() {
// Test that direct sqlx timeout errors convert to FlagError::TimeoutError with type
let sqlx_timeout: FlagError = sqlx::Error::PoolTimedOut.into();
assert!(
matches!(sqlx_timeout, FlagError::TimeoutError(Some(ref timeout_type)) if timeout_type == "pool_timeout")
);
}
#[test]
fn test_direct_sqlx_non_timeout_conversion() {
// Test that direct non-timeout sqlx errors are handled correctly
let sqlx_error: FlagError = sqlx::Error::RowNotFound.into();
assert!(matches!(sqlx_error, FlagError::RowNotFound));
}
#[test]
fn test_direct_sqlx_transient_conversion_is_503() {
// Transient/connection-level failures propagated via `?` must map to the retryable
// DatabaseUnavailable (503), not DatabaseError (500), so SDKs retry on a DB blip.
let pool_closed: FlagError = sqlx::Error::PoolClosed.into();
assert!(matches!(pool_closed, FlagError::DatabaseUnavailable));
assert_eq!(pool_closed.status_code(), 503);
let io_reset: FlagError = sqlx::Error::Io(std::io::Error::new(
std::io::ErrorKind::ConnectionReset,
"connection reset by peer",
))
.into();
assert!(matches!(io_reset, FlagError::DatabaseUnavailable));
assert_eq!(io_reset.status_code(), 503);
let tls_error: FlagError =
sqlx::Error::Tls(Box::new(std::io::Error::other("TLS handshake failed"))).into();
assert!(matches!(tls_error, FlagError::DatabaseUnavailable));
assert_eq!(tls_error.status_code(), 503);
}
#[test]
fn test_direct_sqlx_internal_fault_stays_500() {
// Genuine internal faults (schema/config problems) are not transient and must
// remain DatabaseError (500) so they are not masked as retryable.
let column_error: FlagError = sqlx::Error::ColumnNotFound("missing".to_string()).into();
assert!(matches!(column_error, FlagError::DatabaseError(_, _)));
assert_eq!(column_error.status_code(), 500);
let config_error: FlagError =
sqlx::Error::Configuration("invalid connection string".into()).into();
assert!(matches!(config_error, FlagError::DatabaseError(_, _)));
assert_eq!(config_error.status_code(), 500);
}
#[test]
fn test_redis_timeout_conversion() {
// Test that Redis timeout errors are converted to FlagError::TimeoutError
let redis_timeout: FlagError = CustomRedisError::Timeout.into();
assert!(
matches!(redis_timeout, FlagError::TimeoutError(Some(ref timeout_type)) if timeout_type == "Redis timeout")
);
}
#[test]
fn test_error_codes_are_non_empty() {
// Verify all error codes are non-empty strings
let errors: Vec<FlagError> = vec![
FlagError::ClientFacing(ClientFacingError::BadRequest("test".to_string())),
FlagError::ClientFacing(ClientFacingError::Unauthorized("test".to_string())),
FlagError::ClientFacing(ClientFacingError::RateLimited),
FlagError::ClientFacing(ClientFacingError::IpRateLimited),
FlagError::ClientFacing(ClientFacingError::TokenRateLimited),
FlagError::ClientFacing(ClientFacingError::BillingLimit),
FlagError::ClientFacing(ClientFacingError::ServiceUnavailable),
FlagError::internal(anyhow::anyhow!("test")),
FlagError::RequestDecodingError("test".to_string()),
serde_json::from_str::<String>("invalid json")
.unwrap_err()
.into(), // RequestParsingError
FlagError::MissingDistinctId,
FlagError::PayloadTooLarge {
decompressed: 5_000_000,
limit: 4 * 1024 * 1024,
},
FlagError::NoTokenError,
FlagError::TokenValidationError,
FlagError::PersonalApiKeyInvalid,
FlagError::PersonalApiKeyInsufficientScopes,
FlagError::SecretApiTokenInvalid,
FlagError::NoAuthenticationProvided,
FlagError::RowNotFound,
FlagError::flag_data_parsing("test parse error"),
FlagError::redis_unavailable(anyhow::anyhow!("connection refused")),
FlagError::DatabaseUnavailable,
FlagError::DatabaseError(sqlx::Error::RowNotFound, Some("test context".to_string())),
FlagError::TimeoutError(None),
FlagError::DependencyNotFound(DependencyType::Flag, 1),
FlagError::DependencyFailed(2),
FlagError::DependencyCycle(DependencyType::Cohort, 2),
FlagError::CohortFiltersParsingError,
FlagError::person_not_found(),
FlagError::cache_miss(),
FlagError::data_parsing(anyhow::anyhow!("bad payload")),
FlagError::batch_evaluation_panicked(),
FlagError::HashKeyOverrideError,
FlagError::RayonSemaphoreTimeout(800),
CookielessManagerError::MissingProperty("test".to_string()).into(), // CookielessError
];
for error in errors {
let code = error.error_code();
assert!(
!code.is_empty(),
"Error code should not be empty for {error:?}"
);
assert!(
!code.contains(' '),
"Error code should not contain spaces: {code}"
);
}
}
#[test]
fn test_status_codes_match_http_semantics() {
// 4xx errors (client errors)
assert_eq!(
FlagError::ClientFacing(ClientFacingError::BadRequest("".into())).status_code(),
400
);
assert_eq!(
FlagError::ClientFacing(ClientFacingError::Unauthorized("".into())).status_code(),
401
);
assert_eq!(
FlagError::ClientFacing(ClientFacingError::BillingLimit).status_code(),
402
);
assert_eq!(
FlagError::ClientFacing(ClientFacingError::RateLimited).status_code(),
429
);
assert_eq!(FlagError::MissingDistinctId.status_code(), 400);
assert_eq!(FlagError::NoTokenError.status_code(), 401);
assert_eq!(FlagError::TokenValidationError.status_code(), 401);
assert_eq!(
FlagError::PayloadTooLarge {
decompressed: 5_000_000,
limit: 4 * 1024 * 1024
}
.status_code(),
413
);
// 5xx errors (server errors)
assert_eq!(FlagError::internal(anyhow::anyhow!("")).status_code(), 500);
assert_eq!(FlagError::DatabaseUnavailable.status_code(), 503);
assert_eq!(
FlagError::redis_unavailable(anyhow::anyhow!("connection refused")).status_code(),
503
);
assert_eq!(FlagError::TimeoutError(None).status_code(), 503);
assert_eq!(
FlagError::ClientFacing(ClientFacingError::ServiceUnavailable).status_code(),
503
);
assert_eq!(FlagError::RowNotFound.status_code(), 500);
// Cache miss errors are now 503 (transient)
assert_eq!(FlagError::person_not_found().status_code(), 503);
// Semaphore timeout is 504 (gateway timeout for ingress retry)
assert_eq!(FlagError::RayonSemaphoreTimeout(800).status_code(), 504);
}
#[test]
fn test_status_code_ranges() {
// All client-facing errors except ServiceUnavailable should be 4xx
let client_4xx_errors = vec![
FlagError::ClientFacing(ClientFacingError::BadRequest("".into())),
FlagError::ClientFacing(ClientFacingError::Unauthorized("".into())),
FlagError::ClientFacing(ClientFacingError::RateLimited),
FlagError::ClientFacing(ClientFacingError::BillingLimit),
];
for error in client_4xx_errors {
let status = error.status_code();
assert!(
(400..500).contains(&status),
"Expected 4xx for {error:?}, got {status}"
);
}
// Server errors should be 5xx
let server_errors = vec![
FlagError::internal(anyhow::anyhow!("")),
FlagError::RowNotFound,
FlagError::CohortFiltersParsingError,
FlagError::data_parsing(anyhow::anyhow!("bad payload")),
];
for error in server_errors {
let status = error.status_code();
assert!(status >= 500, "Expected 5xx for {error:?}, got {status}");
}
}
#[test]
fn test_error_code_consistency_with_is_5xx() {
// Verify that status_code() >= 500 matches is_5xx() for ALL 5xx errors
let errors_5xx = vec![
FlagError::internal(anyhow::anyhow!("test")),
FlagError::DatabaseError(sqlx::Error::RowNotFound, None),
FlagError::RowNotFound,
FlagError::DependencyNotFound(DependencyType::Flag, 1),
FlagError::DependencyFailed(2),
FlagError::CohortFiltersParsingError,
FlagError::DependencyCycle(DependencyType::Cohort, 2),
FlagError::data_parsing(anyhow::anyhow!("bad payload")),
FlagError::batch_evaluation_panicked(),
FlagError::HashKeyOverrideError,
FlagError::RayonSemaphoreTimeout(800),
FlagError::flag_data_parsing("test"),
FlagError::redis_unavailable(anyhow::anyhow!("connection refused")),
FlagError::DatabaseUnavailable,
FlagError::TimeoutError(None),
FlagError::cache_miss(),
FlagError::person_not_found(),
FlagError::ClientFacing(ClientFacingError::ServiceUnavailable),
];
for error in errors_5xx {
let is_5xx = error.is_5xx();
let status = error.status_code();
assert!(
is_5xx,
"is_5xx() should be true for {error:?} (status={status})"
);
assert!(
status >= 500,
"status_code() should be >= 500 for {error:?}, got {status}"
);
}
}
#[test]
fn test_is_token_not_found() {
// These errors mean the token definitively doesn't map to a team
assert!(FlagError::TokenValidationError.is_token_not_found());
assert!(FlagError::RowNotFound.is_token_not_found());
// Transient infrastructure errors should NOT be treated as "not found"
assert!(!FlagError::cache_miss().is_token_not_found());
assert!(
!FlagError::redis_unavailable(anyhow::anyhow!("connection refused"))
.is_token_not_found()
);
assert!(!FlagError::DatabaseUnavailable.is_token_not_found());
assert!(!FlagError::TimeoutError(None).is_token_not_found());
assert!(!FlagError::TimeoutError(Some("pool_timeout".to_string())).is_token_not_found());
assert!(!FlagError::DatabaseError(sqlx::Error::PoolTimedOut, None).is_token_not_found());
assert!(!FlagError::internal(anyhow::anyhow!("serialization failed")).is_token_not_found());
assert!(!FlagError::data_parsing(anyhow::anyhow!("bad payload")).is_token_not_found());
}
#[test]
fn test_specific_error_codes() {
// Verify specific error codes match expected values
assert_eq!(
FlagError::ClientFacing(ClientFacingError::RateLimited).error_code(),
"rate_limited"
);
assert_eq!(FlagError::NoTokenError.error_code(), "missing_token");
assert_eq!(
FlagError::TokenValidationError.error_code(),
"invalid_token"
);
assert_eq!(
FlagError::MissingDistinctId.error_code(),
"missing_distinct_id"
);
assert_eq!(
FlagError::TimeoutError(Some("pool".to_string())).error_code(),
"timeout"
);
assert_eq!(
FlagError::DatabaseUnavailable.error_code(),
"database_unavailable"
);
assert_eq!(
FlagError::redis_unavailable(anyhow::anyhow!("connection refused")).error_code(),
"redis_unavailable"
);
}
#[test]
fn test_error_codes_are_unique() {
use std::collections::HashSet;
// All error variants that should have unique error codes
let errors: Vec<FlagError> = vec![
FlagError::ClientFacing(ClientFacingError::BadRequest("test".to_string())),
FlagError::ClientFacing(ClientFacingError::Unauthorized("test".to_string())),
FlagError::ClientFacing(ClientFacingError::RateLimited),
FlagError::ClientFacing(ClientFacingError::IpRateLimited),
FlagError::ClientFacing(ClientFacingError::TokenRateLimited),
FlagError::ClientFacing(ClientFacingError::BillingLimit),
FlagError::ClientFacing(ClientFacingError::ServiceUnavailable),
FlagError::internal(anyhow::anyhow!("test")),
FlagError::RequestDecodingError("test".to_string()),
serde_json::from_str::<String>("invalid json")
.unwrap_err()
.into(), // RequestParsingError
FlagError::MissingDistinctId,
FlagError::PayloadTooLarge {
decompressed: 5_000_000,
limit: 4 * 1024 * 1024,
},
FlagError::NoTokenError,
FlagError::TokenValidationError,
FlagError::PersonalApiKeyInvalid,
FlagError::PersonalApiKeyInsufficientScopes,
FlagError::SecretApiTokenInvalid,
FlagError::NoAuthenticationProvided,
FlagError::RowNotFound,
FlagError::flag_data_parsing("test parse error"),
FlagError::redis_unavailable(anyhow::anyhow!("connection refused")),
FlagError::DatabaseUnavailable,
FlagError::DatabaseError(sqlx::Error::RowNotFound, Some("test context".to_string())),
FlagError::TimeoutError(None),
FlagError::DependencyNotFound(DependencyType::Flag, 1),
FlagError::DependencyFailed(2),
FlagError::DependencyCycle(DependencyType::Cohort, 2),
FlagError::CohortFiltersParsingError,
FlagError::person_not_found(),
FlagError::cache_miss(),
FlagError::data_parsing(anyhow::anyhow!("bad payload")),
FlagError::batch_evaluation_panicked(),
FlagError::HashKeyOverrideError,
FlagError::RayonSemaphoreTimeout(800),
CookielessManagerError::MissingProperty("test".to_string()).into(),
];
let mut seen_codes: HashSet<&'static str> = HashSet::new();
for error in &errors {
let code = error.error_code();
assert!(
seen_codes.insert(code),
"Duplicate error code '{code}' found for {error:?}"
);
}
}
}