Enrichment Error Handling

RiskOS™ integrates with multiple enrichment modules and data partners. To ensure reliability, the platform includes built-in mechanisms to handle errors gracefully and allow workflows to continue executing even when individual steps encounter issues.

Retry mechanism

RiskOS™ automatically retries failed enrichment API calls up to three times, with a maximum wait time of 2,000 ms per attempt.

If you need to adjust retry behavior for your account, please contact [email protected].

Handling enrichment failures in workflows

• If an Enrichment step fails, its output variable is set to null.
• Downstream Condition steps will then evaluate to False, allowing you to define fallback logic.
• Example: Use the is set or is not set operator on an enrichment output field to branch your workflow when enrichment data is missing or invalid.
• You can also configure fallback enrichment steps and logic directly in the Workflow Editor:
  • Chain alternative enrichment providers or internal modules if a primary enrichment fails.
  • Fallback enrichments ensure continuity of decisioning without requiring manual intervention.

This ensures workflows continue executing instead of failing completely.

Identifying errors in API responses

All enrichment results are returned in the evaluation API response under the data_enrichments array.

Each enrichment block includes:

• status_code → The HTTP response code from the data service.
• error_message → Details about the error, if present.
• request → The payload sent to the service.
• response → The service’s raw response. Its shape depends on whether the call succeeded — see Reading the response field.

Tip: An enrichment call is considered successful if status_code = 200. Any non-200 response means the enrichment failed.

Reading the response field

The structure of response differs between a successful and a failed enrichment call:

• On success (status_code 200), the provider's payload sits at the top level of response. A successful Prefill returns the identity data under response.prefill, a successful Email Risk enrichment returns response.emailRisk, and so on. Socure enrichments always include a referenceId.
• On failure (any non-200 status_code), RiskOS™ captures the provider's raw error body as a JSON-encoded string under a nested response.response field. Parse that string to read the underlying error — a Socure error envelope with status, msg, and data.

A nested response.response is always an error artifact. It never carries successful identity data, so treat its presence as a failed enrichment.

{
  "enrichment_name": "Socure Prefill",
  "enrichment_provider": "Socure",
  "enrichment_endpoint": "https://sandbox.dev.socure.com/api/3.0/EmailAuthScore",
  "status_code": 400,
  "request": {
    "modules": ["prefill"],
    "firstName": "Sarah",
    "surName": "Miles"
  },
  "response": {
    "response": "{\"status\":\"Error\",\"referenceId\":\"69bd01bf-1048-4d7e-b9a1-5833fc7caa53\",\"data\":{\"parameters\":[\"Missing required parameters for module: prefill\"]},\"msg\":\"Missing required parameters for module: prefill\"}"
  },
  "is_source_cache": false,
  "total_attempts": 1
}

How failed enrichments affect the decision

A failed enrichment does not stop the workflow. RiskOS™ sets the enrichment's output to null and continues to the Decision step, so the evaluation still returns a decision — for example, ACCEPT.

Keep these points in mind when you interpret a decision:

• A failed enrichment is not scored. Its signals are absent from the decision unless you add fallback logic. The decision reflects only the enrichments that succeeded, and it does not automatically change when an enrichment fails.
• ACCEPT does not confirm a failed check passed. If a compliance enrichment such as Watchlist returns a non-200 status_code, that screening did not run. Do not treat the ACCEPT as a cleared screening.
• There is no top-level "incomplete data" flag. The response carries no single field that signals a degraded decision. To detect one, inspect each data_enrichments[].status_code and confirm that the enrichments your decision depends on returned 200.
• Escalate critical failures. To avoid deciding on incomplete data, add a Condition step that routes to review — or to a fallback enrichment — when a required enrichment output isn't set. See Handling enrichment failures in workflows.

Example request

{
  "enrichment_name": "Socure Email Risk",
  "enrichment_endpoint": "https://sandbox.dev.socure.com/api/3.0/EmailAuthScore",
  "enrichment_provider": "Socure",
  "status_code": 500,
  "error_message": "Internal Server Error. Unable to process email risk request at this time.",
  "request": {
    "modules": [
      "emailrisk"
    ],
    "email": "[email protected]"
  },
  "is_source_cache": false,
  "total_attempts": 3
}