diff --git a/api-references/data/insights.json b/api-references/data/insights.json
index b2d2b557..6e38bb16 100644
--- a/api-references/data/insights.json
+++ b/api-references/data/insights.json
@@ -137,14 +137,49 @@
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "AuthenticationErrorResponse": {
- "summary": "AuthenticationErrorResponse",
+ "AuthenticationError": {
+ "summary": "Authentication Error",
"value": {
- "errorCode": "401",
- "errorMsg": "Unable to fetch FIU config",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "auth_unauthorized",
+ "type": "auth",
+ "message": "Unable to fetch FIU config. Please pass `x-client-id`, `x-client-secret`, `x-product-account-id` headers properly.",
+ "details": {
+ "http_status": 401
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "404 Template Not Found": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "TemplateNotFound": {
+ "summary": "Template not found",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_template_not_found",
+ "type": "validation",
+ "message": "Template with id 593ee9b4-58ad-4e97-5df5-afc65a8b5970 not found",
+ "details": {
+ "param": "templateId",
+ "error": "field not found"
+ }
+ }
}
}
}
@@ -159,14 +194,21 @@
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "ValidationErrorResponse": {
- "summary": "ValidationErrorResponse",
+ "ValidationError": {
+ "summary": "Validation Error",
"value": {
- "errorCode": "422",
- "errorMsg": "field required -> account",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_validation_error",
+ "type": "validation",
+ "message": "Request validation failed",
+ "details": {
+ "field": "refId",
+ "error": "field required"
+ }
+ }
}
}
}
@@ -181,14 +223,20 @@
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "ServerErrorResponse": {
- "summary": "ServerErrorResponse",
+ "ServerError": {
+ "summary": "Server Error",
"value": {
- "errorCode": "500",
- "errorMsg": "Internal Server Error",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "internal_error",
+ "type": "internal",
+ "message": "Internal Server Error",
+ "details": {
+ "http_status": 500
+ }
+ }
}
}
}
@@ -307,6 +355,239 @@
}
}
},
+ "400 Empty Template Name": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "EmptyTemplateName": {
+ "summary": "Empty template name",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_empty_template_name",
+ "type": "validation",
+ "message": "Template name cannot be empty",
+ "details": {
+ "field": "name",
+ "error": "field required"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "400 No Insights Provided": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "NoInsightsProvided": {
+ "summary": "No insights provided",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_validation_error",
+ "type": "validation",
+ "message": "Insights must be provided in a template",
+ "details": {
+ "field": "insights",
+ "error": "field required"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "400 No Valid Insights": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "NoValidInsights": {
+ "summary": "No valid insights",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_validation_error",
+ "type": "validation",
+ "message": "At least one static, configurable, or aggregated insight must be provided in a template",
+ "details": {
+ "field": "insights",
+ "error": "field required"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "400 Duplicate Ref Key Config": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "DuplicateRefKeyConfig": {
+ "summary": "Duplicate ref key config",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_validation_error",
+ "type": "validation",
+ "message": "Use different ref_key for following, monthly_salary_credits config already exists: {conflicts}",
+ "details": {
+ "field": "ref_key",
+ "error": "field duplicate"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "400 Integrity Error": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "IntegrityError": {
+ "summary": "Integrity error",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_validation_error",
+ "type": "validation",
+ "message": "Cannot create insights with same ref_key",
+ "details": {
+ "field": "ref_key",
+ "error": "field duplicate"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "400 Duplicate Ref Keys": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "DuplicateRefKeys": {
+ "summary": "Duplicate ref keys",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_duplicate_ref_key",
+ "type": "validation",
+ "message": "Duplicate ref_keys found in request: {duplicate_ref_keys}",
+ "details": {
+ "field": "ref_keys",
+ "error": "field duplicate"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "400 Invalid Ref Key Format": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "InvalidRefKeyFormat": {
+ "summary": "Invalid ref key format",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_invalid_ref_key",
+ "type": "validation",
+ "message": "Invalid ref_key format: \"Monthly EOD Balance\". Must not contain spaces or special characters.",
+ "details": {
+ "field": "ref_key",
+ "error": "invalid format"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "400 Invalid Insight Name": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "InvalidInsightName": {
+ "summary": "Invalid insight name",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_invalid_insight_name",
+ "type": "validation",
+ "message": "Invalid insight name: {insight_name}. Must start with 'static_', 'configurable_', or 'aggregated_'",
+ "details": {
+ "field": "insight_name",
+ "error": "invalid format"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+
"401": {
"description": "Authentication Error",
"content": {
@@ -315,14 +596,49 @@
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "AuthenticationErrorResponse": {
- "summary": "AuthenticationErrorResponse",
+ "AuthenticationError": {
+ "summary": "Authentication Error",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "auth_unauthorized",
+ "type": "auth",
+ "message": "Unable to fetch FIU config. Please pass `x-client-id`, `x-client-secret`, `x-product-account-id` headers properly.",
+ "details": {
+ "http_status": 401
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "404 Insight Not Found": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "InsightNotFound": {
+ "summary": "Insight not found",
"value": {
- "errorCode": "401",
- "errorMsg": "Unable to fetch FIU config",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_insight_not_found",
+ "type": "validation",
+ "message": "Insights not found (case-sensitive): {missing_insights}",
+ "details": {
+ "field": "insights",
+ "error": "field not found"
+ }
+ }
}
}
}
@@ -337,36 +653,80 @@
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "ValidationErrorResponse": {
- "summary": "ValidationErrorResponse",
+ "ValidationError": {
+ "summary": "Validation Error",
"value": {
- "errorCode": "422",
- "errorMsg": "field required -> account",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_validation_error",
+ "type": "validation",
+ "message": "Request validation failed",
+ "details": {
+ "total_errors": 1,
+ "error_message": [
+ "field required -> refId"
+ ]
+ }
+ }
}
}
}
}
}
},
- "500": {
- "description": "Internal Server Error",
+ "500 Insight Master Not Found": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "InsightMasterNotFound": {
+ "summary": "Insight master not found",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_insight_not_found",
+ "type": "internal",
+ "message": "Unexpected error: Insight master not found after validation: {item.insight}",
+ "details": {
+ "field": "insight_master",
+ "error": "field not found"
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "500 Server Error": {
+ "description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "ServerErrorResponse": {
- "summary": "ServerErrorResponse",
+ "ServerError": {
+ "summary": "Server Error",
"value": {
- "errorCode": "500",
- "errorMsg": "Internal Server Error",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "internal_error",
+ "type": "internal",
+ "message": "Internal Server Error",
+ "details": {
+ "http_status": 500
+ }
+ }
}
}
}
@@ -482,6 +842,64 @@
}
}
},
+ "400 Invalid Ref ID Format": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "InvalidRefIdFormat": {
+ "summary": "Invalid refId format",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_invalid_ref_id",
+ "type": "validation",
+ "message": "Invalid refId: must not contain spaces or special characters.",
+ "details": {
+ "param": "refId",
+ "http_status": 400
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "400 Missing Linked Acc Ref": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "MissingLinkedAccRef": {
+ "summary": "Missing linked account reference",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_missing_linked_acc_ref",
+ "type": "validation",
+ "message": "Linked acc ref is required for each account",
+ "details": {
+ "param": "linked_acc_ref",
+ "http_status": 400
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
"401": {
"description": "Authentication Error",
"content": {
@@ -490,14 +908,20 @@
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "AuthenticationErrorResponse": {
- "summary": "AuthenticationErrorResponse",
+ "AuthenticationError": {
+ "summary": "Authentication Error",
"value": {
- "errorCode": "401",
- "errorMsg": "Unable to fetch FIU config",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "auth_unauthorized",
+ "type": "auth",
+ "message": "Unable to fetch FIU config. Please pass `x-client-id`, `x-client-secret`, `x-product-account-id` headers properly.",
+ "details": {
+ "http_status": 401
+ }
+ }
}
}
}
@@ -512,36 +936,76 @@
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "ValidationErrorResponse": {
- "summary": "ValidationErrorResponse",
+ "ValidationError": {
+ "summary": "Validation Error",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_validation_error",
+ "type": "validation",
+ "message": "Request validation failed",
+ "details": {
+ "total_errors": 1,
+ "error_message": [
+ "field required -> refId"
+ ]
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "500 Transaction Service Error": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "TransactionServiceError": {
+ "summary": "Transaction service error",
"value": {
- "errorCode": "422",
- "errorMsg": "field required -> account",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "internal_error",
+ "type": "internal",
+ "message": "{error message from service}",
+ "details": {
+ "param": "service",
+ "http_status": 500
+ }
+ }
}
}
}
}
}
},
- "500": {
- "description": "Internal Server Error",
+ "500 Internal Server Error": {
+ "description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "ServerErrorResponse": {
- "summary": "ServerErrorResponse",
+ "UnexpectedError": {
+ "summary": "Unexpected error",
"value": {
- "errorCode": "500",
- "errorMsg": "Internal Server Error",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "code": "internal_error",
+ "type": "internal",
+ "message": "Internal Server Error",
+ "details": {
+ "param": "exception_type",
+ "http_status": 500
+ }
}
}
}
@@ -793,6 +1257,35 @@
}
}
},
+ "400 Invalid Report Id": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "InvalidReportId": {
+ "summary": "Invalid report ID",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_invalid_ref_id",
+ "type": "validation",
+ "message": "Invalid report id",
+ "details": {
+ "param": "reportId",
+ "http_status": 400
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
"401": {
"description": "Authentication Error",
"content": {
@@ -801,14 +1294,49 @@
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "AuthenticationErrorResponse": {
- "summary": "AuthenticationErrorResponse",
+ "AuthenticationError": {
+ "summary": "Authentication Error",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "auth_unauthorized",
+ "type": "auth",
+ "message": "Unable to fetch FIU config. Please pass `x-client-id`, `x-client-secret`, `x-product-account-id` headers properly.",
+ "details": {
+ "http_status": 401
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "404 Report Not Found": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "ReportNotFound": {
+ "summary": "Report not found",
"value": {
- "errorCode": "401",
- "errorMsg": "Unable to fetch FIU config",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_report_not_found",
+ "type": "validation",
+ "message": "Unable to find report with id: 293ee9b4-58ad-4e97-9df5-afc65a8b5970",
+ "details": {
+ "param": "reportId",
+ "http_status": 404
+ }
+ }
}
}
}
@@ -823,14 +1351,23 @@
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "ValidationErrorResponse": {
- "summary": "ValidationErrorResponse",
+ "ValidationError": {
+ "summary": "Validation Error",
"value": {
- "errorCode": "422",
- "errorMsg": "field required -> account",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_validation_error",
+ "type": "validation",
+ "message": "Request validation failed",
+ "details": {
+ "total_errors": 1,
+ "error_message": [
+ "field required -> refId"
+ ]
+ }
+ }
}
}
}
@@ -845,14 +1382,20 @@
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "ServerErrorResponse": {
- "summary": "ServerErrorResponse",
+ "ServerError": {
+ "summary": "Server Error",
"value": {
- "errorCode": "500",
- "errorMsg": "Internal Server Error",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "internal_error",
+ "type": "internal",
+ "message": "Internal Server Error",
+ "details": {
+ "http_status": 500
+ }
+ }
}
}
}
@@ -866,7 +1409,7 @@
"Insight generation"
],
"summary": "Create Insights",
- "description": "Call this API with the template-id received from Setu along with a ref_id, to trigger an Report generation job. The created Report will be shared via a notification to the endpoint configured by the FIU.This API will respond with a report-id, which can also be used to fetch the generated Report.",
+ "description": "Call this API with the template-id received from Setu along with a refId, to trigger an Report generation job. The created Report will be shared via a notification to the endpoint configured by the FIU.This API will respond with a report-id, which can also be used to fetch the generated Report.",
"operationId": "process_insights_v3_insight_post",
"parameters": [
{
@@ -957,14 +1500,20 @@
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "AuthenticationErrorResponse": {
- "summary": "AuthenticationErrorResponse",
+ "AuthenticationError": {
+ "summary": "Authentication Error",
"value": {
- "errorCode": "401",
- "errorMsg": "Unable to fetch FIU config",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "auth_unauthorized",
+ "type": "auth",
+ "message": "Unable to fetch FIU config. Please pass `x-client-id`, `x-client-secret`, `x-product-account-id` headers properly.",
+ "details": {
+ "http_status": 401
+ }
+ }
}
}
}
@@ -979,14 +1528,23 @@
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "ValidationErrorResponse": {
- "summary": "ValidationErrorResponse",
+ "ValidationError": {
+ "summary": "Validation Error",
"value": {
- "errorCode": "422",
- "errorMsg": "field required -> account",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_validation_error",
+ "type": "validation",
+ "message": "Request validation failed",
+ "details": {
+ "total_errors": 1,
+ "error_message": [
+ "field required -> refId"
+ ]
+ }
+ }
}
}
}
@@ -1001,58 +1559,107 @@
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "ServerErrorResponse": {
- "summary": "ServerErrorResponse",
+ "ServerError": {
+ "summary": "Server Error",
"value": {
- "errorCode": "500",
- "errorMsg": "Internal Server Error",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "internal_error",
+ "type": "internal",
+ "message": "Internal Server Error",
+ "details": {
+ "http_status": 500
+ }
+ }
}
}
}
}
}
},
- "400": {
- "description": "Bad Request",
+ "400 Invalid RefId Format": {
+ "description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "RequestErrorResponse": {
- "summary": "RequestErrorResponse",
+ "InvalidRefIdFormat": {
+ "summary": "Invalid refId format",
"value": {
- "errorCode": "400",
- "errorMsg": "Empty data_ids input",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_invalid_ref_id",
+ "type": "validation",
+ "message": "Invalid refId: must not contain spaces or special characters.",
+ "details": {
+ "param": "refId",
+ "http_status": 400
+ }
+ }
}
}
}
}
}
},
- "404": {
- "description": "Not Found Error",
+ "404 RefId Not Found": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ },
+ "examples": {
+ "RefIdNotFound": {
+ "summary": "Ref ID not found",
+ "value": {
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_ref_id_not_found",
+ "type": "validation",
+ "message": "Unable to find refId: 293ee9b4-58ad-4e97-9df5-afc65a8b5970",
+ "details": {
+ "param": "refId",
+ "http_status": 404
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ },
+ "404 Template Not Found": {
+ "description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "NotFoundResponse": {
- "summary": "NotFoundResponse",
+ "TemplateNotFound": {
+ "summary": "Template not found",
"value": {
- "errorCode": "404",
- "errorMsg": "Unable to find FIData with id: 4e8e6d50-2dd4-43d0-a79a-5348b935ecf4",
- "timestamp": "2023-04-18T17:10:12.904153",
- "ver": "1",
- "txnid": "4e8e6d50-2dd4-43d0-a79a-5348b935ecf4"
+ "timestamp": "2025-08-20 11:02:49.657",
+ "version": "0.78.1",
+ "txnid": "",
+ "error": {
+ "code": "api_template_not_found",
+ "type": "validation",
+ "message": "Unable to find template with id: 453ee9b4-58ad-4e97-9df5-afc65a8b5970",
+ "details": {
+ "param": "templateId",
+ "http_status": 404
+ }
+ }
}
}
}
@@ -1367,7 +1974,7 @@
}
},
"400": {
- "description": "Bad Request",
+ "description": "Validation Error",
"content": {
"application/json": {
"schema": {
@@ -1422,8 +2029,8 @@
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "AuthenticationErrorResponse": {
- "summary": "AuthenticationErrorResponse",
+ "AuthenticationError": {
+ "summary": "Authentication Error",
"value": {
"timestamp": "2025-08-20 06:48:20.058",
"version": "0.83.0",
@@ -1444,15 +2051,15 @@
}
},
"404": {
- "description": "Not Found",
+ "description": "RefId Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
- "NotFoundResponse": {
- "summary": "NotFoundResponse",
+ "RefIdNotFound": {
+ "summary": "Unable to find ref_id",
"value": {
"timestamp": "2025-08-20 06:48:20.058",
"version": "0.83.0",
@@ -1503,7 +2110,7 @@
}
},
"500": {
- "description": "Internal Server Error",
+ "description": "Internal Error",
"content": {
"application/json": {
"schema": {
@@ -2210,36 +2817,64 @@
"ErrorResponse": {
"title": "ErrorResponse",
"required": [
- "errorCode",
- "errorMsg"
+ "timestamp",
+ "version",
+ "txnid",
+ "error"
],
"type": "object",
"properties": {
- "errorCode": {
- "title": "Errorcode",
- "type": "string"
- },
- "errorMsg": {
- "title": "Errormsg",
- "type": "string"
- },
"timestamp": {
"title": "Timestamp",
"type": "string",
- "format": "date-time"
+ "format": "date-time",
+ "description": "Timestamp when the error occurred"
},
"version": {
"title": "Version",
"type": "string",
- "default": "0.74.0"
+ "description": "API version"
},
"txnid": {
- "title": "Txnid",
+ "title": "Transaction ID",
"type": "string",
- "default": ""
+ "description": "Transaction identifier"
+ },
+ "error": {
+ "title": "Error",
+ "type": "object",
+ "required": [
+ "code",
+ "type",
+ "message"
+ ],
+ "properties": {
+ "code": {
+ "title": "Error Code",
+ "$ref": "#/components/schemas/ErrorCode",
+ "description": "Unique identifier for specific error conditions"
+ },
+ "type": {
+ "title": "Error Type",
+ "$ref": "#/components/schemas/ErrorType",
+ "description": "Category of the error"
+ },
+ "message": {
+ "title": "Error Message",
+ "type": "string",
+ "description": "Human-readable description of the error"
+ },
+ "details": {
+ "title": "Error Details",
+ "type": "object",
+ "description": "Additional error context",
+ "additionalProperties": true
+ }
+ }
}
}
},
+
"FIDataBlockCreateResponse": {
"title": "FIDataBlockCreateResponse",
"required": [
@@ -2912,6 +3547,18 @@
}
}
},
+ "ReportJobStatus": {
+ "title": "ReportJobStatus",
+ "enum": [
+ "in-progress",
+ "complete",
+ "failed",
+ "queued",
+ "pdf_in_progress"
+ ],
+ "type": "string",
+ "description": "Status of the report generation job"
+ },
"ReportJobResponseBody": {
"title": "ReportJobResponseBody",
"required": [
@@ -2927,7 +3574,7 @@
},
"status": {
"title": "Status",
- "type": "string"
+ "$ref": "#/components/schemas/ReportJobStatus"
},
"reason": {
"title": "Reason",
@@ -5345,6 +5992,51 @@
"type": "string"
}
}
+ },
+ "ErrorCode": {
+ "title": "ErrorCode",
+ "type": "string",
+ "enum": [
+ "api_validation_error",
+ "api_invalid_request",
+ "api_empty_template_name",
+ "api_template_not_found",
+ "api_report_not_found",
+ "api_ref_id_not_found",
+ "api_invalid_ref_id",
+ "api_template_conflict",
+ "api_missing_linked_acc_ref",
+ "api_duplicate_ref_key",
+ "api_invalid_ref_key",
+ "api_invalid_insight_name",
+ "api_insight_not_found",
+ "ins_data_missing",
+ "ins_insufficient_history",
+ "ins_invalid_format",
+ "ins_computation_error",
+ "auth_unauthorized",
+ "auth_forbidden",
+ "rate_limit_exceeded",
+ "upstream_error",
+ "internal_error",
+ "business_error"
+ ],
+ "description": "API-level error codes for v3 endpoints"
+ },
+ "ErrorType": {
+ "title": "ErrorType",
+ "type": "string",
+ "enum": [
+ "auth",
+ "validation",
+ "rate_limit",
+ "upstream",
+ "internal",
+ "business",
+ "insight",
+ "config"
+ ],
+ "description": "Error type categories"
}
}
}
diff --git a/content/data/insights/notifications.mdx b/content/data/insights/notifications.mdx
index 34919472..5c087eba 100644
--- a/content/data/insights/notifications.mdx
+++ b/content/data/insights/notifications.mdx
@@ -13,59 +13,77 @@ The `base_url` is your server URL configured to receive notifications, which is
-#### Insights generated notification
+## Insights generated notification
This notification is used to communicate the generated insights which was requested by you in
Create Insight Report API.
-###### Notification payload
+## Field Descriptions
-Setu will post this payload to your notification endpoint when Insights report is successfully generated.
+The table below describes each field in the notification payload:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `version` | `string` | Version of the Insights API (e.g., "v3") |
+| `notificationId` | `UUID` | Unique identifier for this specific notification |
+| `type` | `string` | Type of notification (always "INSIGHT_STATUS_UPDATE" for insights) |
+| `timestamp` | `datetime` | ISO 8601 timestamp when the notification was sent |
+| `reportId` | `UUID` | Reference ID of the insights generation report. Use this to fetch insights via the Get Insights API |
+| `status` | `enum` | Status of insight processing: `SUCCESS`, `PARTIAL_SUCCESS`, or `FAILURE` |
+| `message` | `string` | Human-readable message describing the current status |
+| `additionalInfo` | `object` | Passthrough field for additional metadata |
+
+#### Success Case
+
+When all insights are successfully generated, you'll receive a notification with `status: "SUCCESS"`. The actual insights data will be available via the Get Insights API.
+
+
+{`{
+ "version": "v3",
+ "notificationId": "b7c8d9e0-f1a2-4b3c-8d4e-9f5a6b7c8d9e",
+ "type": "INSIGHT_STATUS_UPDATE",
+ "timestamp": "2025-06-18T09:39:27.244Z",
+ "reportId": "8af477ff-d97e-4eda-a6c0-b5acd5714262",
+ "status": "SUCCESS",
+ "message": "Insights generation completed successfully",
+ "additionalInfo": {}
+}`}
+
+
+#### Partial Success Case
+
+When some insights are generated successfully while others fail, you'll receive a notification with `status: "PARTIAL_SUCCESS"`. Check the Get Insights API for insight data and any errors.
- {`{
- "type": "INSIGHT_STATUS_UPDATE",
- "timestamp": "2025-06-18 09:39:27.244",
- "reportId": "8af477ff-d97e-4eda-a6c0-b5acd5714262",
- "success": true,
- "data": {
- "status": "READY",
- "insights": [
- {
- "linked_acc_ref": "a1f89fea-4075-4900-9a28-75d9f04b98de",
- "insight_values": {
- "mutualfunds_holdings_summary": {
- "total_current_amount": "0.0",
- "holdings": [
- {
- "isin": "INF277KA1CX6",
- "current_value": "0.0",
- "fund_name": null,
- "amc": "Tata Asset Management Private Limited",
- "units": "0.0"
- }
- ]
- }
- }
- },
- {
- "linked_acc_ref": "8a467ff9-51a5-4c8e-9cec-396dffffda13",
- "insight_values": {
- "bank_account_number": null,
- "fraud_flags": [],
- "insight_errors": {
- "message": "We encountered an issue while calculating some of your financial insights.",
- "affected_insights": [
- "bank_account_number"
- ]
- }
- }
- }
- ]
- },
- "error": {}
-}
-`}
+{`{
+ "version": "v3",
+ "notificationId": "c8d9e0f1-a2b3-4c5d-9e6f-7a8b9c0d1e2f",
+ "type": "INSIGHT_STATUS_UPDATE",
+ "timestamp": "2025-06-18T09:39:27.244Z",
+ "reportId": "8af477ff-d97e-4eda-a6c0-b5acd5714262",
+ "status": "PARTIAL_SUCCESS",
+ "message": "Generation of some insights failed. Call get insights to get the details",
+ "additionalInfo": {}
+}`}
+#### Failure Case
+
+When the entire insight generation process fails, you'll receive a notification with `status: "FAILURE"`.
+
+
+{`{
+ "version": "v3",
+ "notificationId": "d9e0f1a2-b3c4-4d5e-9f6a-8b9c0d1e2f3a",
+ "type": "INSIGHT_STATUS_UPDATE",
+ "timestamp": "2025-06-18T09:39:27.244Z",
+ "reportId": "8af477ff-d97e-4eda-a6c0-b5acd5714262",
+ "status": "FAILURE",
+ "message": "Insights generation failed",
+ "additionalInfo": {}
+}`}
+
+
+
+