API Errors and Latency

Alloy surfaces error and service status data in its API responses in several ways depending on the type of failure. When building your integration, it is strongly recommended to ingest this data programmatically into your internal observability and monitoring systems to maximize visibility.

HTTP Status Errors

Alloy's HTTP status codes are the first layer of error validation and indicate the outcome of each API request. These should be handled in all API call paths and logged to your observability system.

206 Partial Content

206 status codes are used on underlying Evaluations to signify when Alloy was unable to reach a decision due to vendor failures or missing data. When an Evaluation is in a 206 status, the warnings section in the Evaluation API response and dashboard gives additional information about what data was missing:

"warnings": {
  "blocked_actions": [
    {
      "blocked": {
        "action_name": "tmx_pass",
        "action_type": "tag"
      },
      "blocking": {
        "action_name": "Threatmetrix",
        "attribute_name": "Review Status"
      }
    }
  ]
}

Note: For more information, see Policy Design for Service Failures for guidance on managing partial data at the policy level.

Data Service Errors

Beyond top-level HTTP status codes, Alloy provides service-level execution data for each third-party vendor service that runs within a single Evaluation. This is the most granular and actionable source of third-party integration health information available via Alloy's API.

There are two ways to access this data for a Journey Application:

• Using the href object populated on completed_evaluation events and webhooks to make a Get Evaluations request for all relevant Evaluations in the Journey Application.
• Using the Get Journey Application endpoint with the ?fullData=true query parameter, which expands the Evaluation response object in a nested evaluation_result object on completed_evaluation events within the Journey Application _embedded.events[] section.

The Evaluation response includes a services object that shows the execution status of every vendor service in the workflow:

{
	...
  "services": {
    "Ekata": "failed",
    "List": "executed",
    "Threatmetrix": "executed",
    "Equifax Canada": "cached",
    "ComplyAdvantage": "not_executed"
  }
}

Each key corresponds to a service name in the Evaluation Workflow and will have one of the following values:

Monitoring Failed Services: Alloy strongly encourages ingesting data from the services object programmatically to build vendor service monitoring that meets your specific business needs. Alloy also maintains internal service monitoring for early detection and proactive updates to its status page.

Caching Service Responses

If you initiate multiple Journey Application or Evaluation requests with the same Entity data within 30 days, Alloy will automatically use a cached response from most third-party vendor services to prevent duplicate requests and additional charges. Note the following exceptions:

• Alloy will not store a cache for errors or failure messages returned by third-party vendors. Credit bureau frozen file responses are also not cached.
• You can override caching behavior at the Workflow level using the Override Cache config option on Service nodes.

Journey Application State Errors

Journey Applications can also surface errors through their application-level status. The two most important states to instrument are:

Error Status

In the rare event of an unexpected downstream error, a Journey Application will have a status of error and Alloy will send an associated error webhook event. This is a terminal state that typically requires manual resolution. After the root cause is addressed, the application can be resubmitted via the Rerun Journey Application endpoint or through the Alloy dashboard.

Data Request Status

If a request is submitted with missing or incorrectly formatted required fields, the Journey Application will enter a data_request_evaluation status. Resolving this requires submitting corrected data via the Update Journey Application endpoint. This status is generally avoidable by enforcing data validation before sending to Alloy. See Data Validation for more details.

Latency

Alloy's Journey Application API endpoints and webhooks return information about the full status lifecycle of a Journey Application in the _embedded.events[] array. Each event includes a timestamp field indicating when the event occurred in Unix time:

{
  "request_token": ":request_token",
  "timestamp": 1654814723339,
  "type": "update:journeyapplications:sandbox",
  "description": "Notify on sandbox journey application status change",
  "data": {
  	"journey_application_token": ":journey_application_token",
    "type": "started_evaluation",
    "external_partner_id": ":external_partner_id",
    "external_group_id": ":external_group_id",
    "external_application_id": ":external_application_id",
    "timestamp": 1654814725250,
    "evaluation_token": ":evaluation_token",
    "entity_token": ":entity_token",
    "entity_application_token": ":entity_application_token",
    "_embedded": {
        "node": {
            "id": ":node_id",
            "name": null,
            "position": null,
            "type": "workflow",
            "config": {
                "application_token": ":application_token",
                "workflow_token": ":workflow_token",
                "application_version_id": 1,
                "workflow_version_id": 1,
                "workflow_type": null
              }
          }
      },
    "_links": {
        "evaluation": {
            "href": "/v1/evaluations/:evaluation_token"
          },
        "journey_application": {
            "href": "/v1/journeys/:journey_token/applications/:journey_application_token"
          }
      },
    "journey_token": ":journey_token",
    "journey_name": ":journey_name",
    "external_entity_id": ":external_entity_id"
  }
}

Note: The above is an example webhook. Events under _embedded.events[] are structured differently from webhooks and only include what's nested within the data object shown above.

You can use these timestamp values to understand how much time was spent at each step of the Journey. For example, the difference between the timestamp on a started_evaluation event and its corresponding completed_evaluation event gives you the total time the Journey Application spent in that Evaluation.

Keep in mind that some Journey events — like pending_step_up, pending_review, pending_action, and pending_workflow_service — are dependent on an end-user or agent taking action before the Journey can progress. Time between events of these types reflects time Alloy spends waiting rather than processing.

Coming Soon: Alloy will soon offer a dedicated latency API for easily retrieving data-vendor processing times and overall Evaluation processing time for a given Journey Application. For more information, reach out to [email protected] or your dedicated Alloy contact.