From cdde78a24babe872698142de7d22ae150113eaf7 Mon Sep 17 00:00:00 2001 From: Brandon Thomas Date: Wed, 1 Apr 2026 01:46:31 -0400 Subject: [PATCH] error plus error responses --- .../fal_client/src/webhook_api/mod.rs | 3 +- .../src/webhook_api/webhook_error_type.rs | 113 ++++++++++++++++++ .../gpt_image_1p5_fail_content_policy.json | 29 +++++ .../gpt_image_fail_invalid_api_key.json | 29 +++++ .../kling_1p6_pro_file_too_large_error.json | 23 ++++ .../kling_3p0_pro_fail_content_policy.json | 29 +++++ ...no_banana_pro_fail_no_media_generated.json | 30 +++++ .../endpoints/webhooks/fal_webhook_handler.rs | 4 +- 8 files changed, 257 insertions(+), 3 deletions(-) create mode 100644 crates/api_clients/fal_client/src/webhook_api/webhook_error_type.rs create mode 100644 crates/api_clients/fal_client/test_data/webhooks/gpt_image_1p5_fail_content_policy.json create mode 100644 crates/api_clients/fal_client/test_data/webhooks/gpt_image_fail_invalid_api_key.json create mode 100644 crates/api_clients/fal_client/test_data/webhooks/kling_1p6_pro_file_too_large_error.json create mode 100644 crates/api_clients/fal_client/test_data/webhooks/kling_3p0_pro_fail_content_policy.json create mode 100644 crates/api_clients/fal_client/test_data/webhooks/nano_banana_pro_fail_no_media_generated.json diff --git a/crates/api_clients/fal_client/src/webhook_api/mod.rs b/crates/api_clients/fal_client/src/webhook_api/mod.rs index 71e3a2ae06..245b23f899 100644 --- a/crates/api_clients/fal_client/src/webhook_api/mod.rs +++ b/crates/api_clients/fal_client/src/webhook_api/mod.rs @@ -1 +1,2 @@ -pub mod raw_webhook_payload; \ No newline at end of file +pub mod raw_webhook_payload; +pub mod webhook_error_type; \ No newline at end of file diff --git a/crates/api_clients/fal_client/src/webhook_api/webhook_error_type.rs b/crates/api_clients/fal_client/src/webhook_api/webhook_error_type.rs new file mode 100644 index 0000000000..89d6210bf1 --- /dev/null +++ b/crates/api_clients/fal_client/src/webhook_api/webhook_error_type.rs @@ -0,0 +1,113 @@ +use serde::Deserialize; + +/// Machine-readable error type from FAL webhook error payloads. +/// +/// These are the `type` field values from the `detail` array in FAL error responses. +/// See: https://fal.ai/docs/documentation/model-apis/errors +#[derive(Clone, Debug, Eq, PartialEq, Hash, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum WebhookErrorType { + FileTooLarge, + InternalServerError, + GenerationTimeout, + DownstreamServiceError, + DownstreamServiceUnavailable, + ContentPolicyViolation, + NoMediaGenerated, + ImageTooSmall, + ImageTooLarge, + ImageLoadError, + FileDownloadError, + FaceDetectionError, + GreaterThan, + GreaterThanEqual, + LessThan, + LessThanEqual, + MultipleOf, + SequenceTooShort, + SequenceTooLong, + OneOf, + FeatureNotSupported, + InvalidArchive, + ArchiveFileCountBelowMinimum, + ArchiveFileCountExceedsMaximum, + + /// Catch-all for unrecognized error types from FAL. + #[serde(untagged)] + Unknown(String), +} + +impl WebhookErrorType { + pub fn from_str(value: &str) -> Self { + serde_json::from_value(serde_json::Value::String(value.to_string())) + .unwrap_or_else(|_| Self::Unknown(value.to_string())) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn deserialize_known_types() { + let cases = vec![ + ("\"file_too_large\"", WebhookErrorType::FileTooLarge), + ("\"internal_server_error\"", WebhookErrorType::InternalServerError), + ("\"generation_timeout\"", WebhookErrorType::GenerationTimeout), + ("\"downstream_service_error\"", WebhookErrorType::DownstreamServiceError), + ("\"downstream_service_unavailable\"", WebhookErrorType::DownstreamServiceUnavailable), + ("\"content_policy_violation\"", WebhookErrorType::ContentPolicyViolation), + ("\"no_media_generated\"", WebhookErrorType::NoMediaGenerated), + ("\"image_too_small\"", WebhookErrorType::ImageTooSmall), + ("\"image_too_large\"", WebhookErrorType::ImageTooLarge), + ("\"image_load_error\"", WebhookErrorType::ImageLoadError), + ("\"file_download_error\"", WebhookErrorType::FileDownloadError), + ("\"face_detection_error\"", WebhookErrorType::FaceDetectionError), + ("\"greater_than\"", WebhookErrorType::GreaterThan), + ("\"greater_than_equal\"", WebhookErrorType::GreaterThanEqual), + ("\"less_than\"", WebhookErrorType::LessThan), + ("\"less_than_equal\"", WebhookErrorType::LessThanEqual), + ("\"multiple_of\"", WebhookErrorType::MultipleOf), + ("\"sequence_too_short\"", WebhookErrorType::SequenceTooShort), + ("\"sequence_too_long\"", WebhookErrorType::SequenceTooLong), + ("\"one_of\"", WebhookErrorType::OneOf), + ("\"feature_not_supported\"", WebhookErrorType::FeatureNotSupported), + ("\"invalid_archive\"", WebhookErrorType::InvalidArchive), + ("\"archive_file_count_below_minimum\"", WebhookErrorType::ArchiveFileCountBelowMinimum), + ("\"archive_file_count_exceeds_maximum\"", WebhookErrorType::ArchiveFileCountExceedsMaximum), + ]; + + for (json, expected) in cases { + let deserialized: WebhookErrorType = serde_json::from_str(json).unwrap(); + assert_eq!(deserialized, expected, "failed for {}", json); + } + } + + #[test] + fn deserialize_unknown_type() { + let deserialized: WebhookErrorType = serde_json::from_str("\"some_new_error_type\"").unwrap(); + assert_eq!(deserialized, WebhookErrorType::Unknown("some_new_error_type".to_string())); + } + + #[test] + fn from_str_known() { + assert_eq!(WebhookErrorType::from_str("content_policy_violation"), WebhookErrorType::ContentPolicyViolation); + assert_eq!(WebhookErrorType::from_str("face_detection_error"), WebhookErrorType::FaceDetectionError); + } + + #[test] + fn from_str_unknown() { + assert_eq!(WebhookErrorType::from_str("brand_new_type"), WebhookErrorType::Unknown("brand_new_type".to_string())); + } + + #[test] + fn display_known() { + assert_eq!(format!("{}", WebhookErrorType::ContentPolicyViolation), "content_policy_violation"); + assert_eq!(format!("{}", WebhookErrorType::FileTooLarge), "file_too_large"); + } + + #[test] + fn display_unknown() { + assert_eq!(format!("{}", WebhookErrorType::Unknown("foo_bar".to_string())), "foo_bar"); + } +} diff --git a/crates/api_clients/fal_client/test_data/webhooks/gpt_image_1p5_fail_content_policy.json b/crates/api_clients/fal_client/test_data/webhooks/gpt_image_1p5_fail_content_policy.json new file mode 100644 index 0000000000..2b2dd02c69 --- /dev/null +++ b/crates/api_clients/fal_client/test_data/webhooks/gpt_image_1p5_fail_content_policy.json @@ -0,0 +1,29 @@ +{ + "error": "Unexpected status code: 422", + "gateway_request_id": "019d4756-130b-7141-a16c-8f411b785844", + "payload": { + "detail": [ + { + "input": { + "background": "auto", + "image_size": "1536x1024", + "input_fidelity": null, + "num_images": 1, + "openai_api_key": null, + "output_format": "png", + "prompt": "[redacted nsfw query]", + "quality": "medium" + }, + "loc": [ + "body", + "prompt" + ], + "msg": "The content could not be processed because it contained material flagged by a content checker.", + "type": "content_policy_violation", + "url": "https://docs.fal.ai/errors#content_policy_violation" + } + ] + }, + "request_id": "019d4756-130b-7141-a16c-8f411b785844", + "status": "ERROR" +} \ No newline at end of file diff --git a/crates/api_clients/fal_client/test_data/webhooks/gpt_image_fail_invalid_api_key.json b/crates/api_clients/fal_client/test_data/webhooks/gpt_image_fail_invalid_api_key.json new file mode 100644 index 0000000000..3d56fe9c27 --- /dev/null +++ b/crates/api_clients/fal_client/test_data/webhooks/gpt_image_fail_invalid_api_key.json @@ -0,0 +1,29 @@ +{ + "error": "Unexpected status code: 422", + "gateway_request_id": "019d4771-5b51-7480-afc6-67e6e74b9f22", + "payload": { + "detail": [ + { + "input": { + "background": "auto", + "image_size": "1536x1024", + "input_fidelity": null, + "num_images": 1, + "openai_api_key": "REDACTED", + "output_format": "png", + "prompt": "[redacted]", + "quality": "high" + }, + "loc": [ + "body", + "openai_api_key" + ], + "msg": "Invalid API key", + "type": "invalid_api_key", + "url": "https://docs.fal.ai/errors#invalid_api_key" + } + ] + }, + "request_id": "019d4771-5b51-7480-afc6-67e6e74b9f22", + "status": "ERROR" +} \ No newline at end of file diff --git a/crates/api_clients/fal_client/test_data/webhooks/kling_1p6_pro_file_too_large_error.json b/crates/api_clients/fal_client/test_data/webhooks/kling_1p6_pro_file_too_large_error.json new file mode 100644 index 0000000000..bdb0818dfe --- /dev/null +++ b/crates/api_clients/fal_client/test_data/webhooks/kling_1p6_pro_file_too_large_error.json @@ -0,0 +1,23 @@ +{ + "error": "Unexpected status code: 422", + "gateway_request_id": "019d477e-c123-7120-81c7-30d6b58a6720", + "payload": { + "detail": [ + { + "ctx": { + "max_size": 10485760 + }, + "input": "[redacted]", + "loc": [ + "body", + "image_url" + ], + "msg": "File size exceeds the maximum allowed size of 10485760 bytes. Please upload a smaller file.", + "type": "file_too_large", + "url": "https://docs.fal.ai/errors#file_too_large" + } + ] + }, + "request_id": "019d477e-c123-7120-81c7-30d6b58a6720", + "status": "ERROR" +} \ No newline at end of file diff --git a/crates/api_clients/fal_client/test_data/webhooks/kling_3p0_pro_fail_content_policy.json b/crates/api_clients/fal_client/test_data/webhooks/kling_3p0_pro_fail_content_policy.json new file mode 100644 index 0000000000..8f8c619a3e --- /dev/null +++ b/crates/api_clients/fal_client/test_data/webhooks/kling_3p0_pro_fail_content_policy.json @@ -0,0 +1,29 @@ +{ + "error": "Unexpected status code: 422", + "gateway_request_id": "019d4761-035d-7b50-8c42-1521efdd4f34", + "payload": { + "detail": [ + { + "input": { + "aspect_ratio": "16:9", + "cfg_scale": 0.5, + "duration": "3", + "generate_audio": false, + "multi_prompt": null, + "negative_prompt": "blur, distort, and low quality", + "prompt": "[redacted prompt]", + "shot_type": "customize", + "voice_ids": null + }, + "loc": [ + "body" + ], + "msg": "The content could not be processed because it contained material flagged by a content checker.", + "type": "content_policy_violation", + "url": "https://docs.fal.ai/errors#content_policy_violation" + } + ] + }, + "request_id": "019d4761-035d-7b50-8c42-1521efdd4f34", + "status": "ERROR" +} \ No newline at end of file diff --git a/crates/api_clients/fal_client/test_data/webhooks/nano_banana_pro_fail_no_media_generated.json b/crates/api_clients/fal_client/test_data/webhooks/nano_banana_pro_fail_no_media_generated.json new file mode 100644 index 0000000000..f9404fed3d --- /dev/null +++ b/crates/api_clients/fal_client/test_data/webhooks/nano_banana_pro_fail_no_media_generated.json @@ -0,0 +1,30 @@ +{ + "error": "Unexpected status code: 422", + "gateway_request_id": "019d475a-291a-7681-81dc-b27d2489beae", + "payload": { + "detail": [ + { + "input": { + "aspect_ratio": "16:9", + "enable_web_search": false, + "limit_generations": false, + "num_images": 1, + "output_format": "png", + "prompt": "[nsfw prompt redacted]", + "resolution": "1K", + "safety_tolerance": "4", + "seed": null, + "sync_mode": false + }, + "loc": [ + "body" + ], + "msg": "The model did not generate the expected output for this prompt. This may occur for several reasons, including unsafe content, a prompt that is incompatible with the selected media type (e.g., prompting an image model to generate audio), references to missing attachments, or other cases where the input cannot be processed as the requested output type. Please review your inputs and try again. If the issue persists, contact support.", + "type": "no_media_generated", + "url": "https://docs.fal.ai/errors#no_media_generated" + } + ] + }, + "request_id": "019d475a-291a-7681-81dc-b27d2489beae", + "status": "ERROR" +} \ No newline at end of file diff --git a/crates/service/web/storyteller_web/src/http_server/endpoints/webhooks/fal_webhook_handler.rs b/crates/service/web/storyteller_web/src/http_server/endpoints/webhooks/fal_webhook_handler.rs index 811b4dad75..85c078189f 100644 --- a/crates/service/web/storyteller_web/src/http_server/endpoints/webhooks/fal_webhook_handler.rs +++ b/crates/service/web/storyteller_web/src/http_server/endpoints/webhooks/fal_webhook_handler.rs @@ -110,8 +110,8 @@ pub async fn fal_webhook_handler( FalWebhookError::BadInput("Could not decode request body to UTF-8".to_string()) })?; - info!("Received FAL webhook body: {:?}", webhook_payload); - + info!("Received FAL webhook body: {}", webhook_payload); + let webhook_payload = RawWebhookPayload::try_from_json(&webhook_payload) .map_err(|err| { error!("Fal Webhook: could not parse webhook payload as JSON: {:?}", err);