--- updatedAt: 2026-09-09T20:05:36.000Z agentTools: projectIndex: https://developer.alloy.com/public/llms.txt --- # 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. | Status Class | Meaning | Action | | ------------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **2xx** | Success — the request was received and processed as expected. | No action needed. | | **4xx** | Client errors — the request was malformed, unauthorized, or referenced a resource that doesn't exist. | Not retryable without addressing the underlying cause. See [Data Validation](https://developer.alloy.com/public/docs/data-validation) for troubleshooting common data format issues. | | **5xx** | Server errors — Alloy encountered an internal error. | Typically transient and safe to retry with exponential backoff. See [Request Handling and Retries](https://developer.alloy.com/public/docs/request-handling-retry) for more guidance on retries. | ### 206 Partial Content [`206` status codes](https://help.alloy.com/hc/en-us/articles/5801219208731-Partial-Status) 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: ```json "warnings": { "blocked_actions": [ { "blocked": { "action_name": "High Fraud Score", "action_type": "tag" }, "blocking": { "action_name": "Threatmetrix", "attribute_name": "Review Status" } } ] } ``` > **Note:** For more information, see [Policy Design for Service Failures](https://developer.alloy.com/public/docs/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: ```json { ... "services": { "Ekata": "failed", "Custom List": "executed", "Sentilink": "cached", "ComplyAdvantage": "not_executed" } } ``` Each key corresponds to a service name in the Evaluation Workflow and will have one of the following values: | Value | Definition | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `executed` | The service ran and returned a response successfully. | | `cached` | The service returned a previously cached response (within the 30-day cache window). | | `failed` | The service was attempted but returned an error or no data. Logging this status is especially critical for identifying vendor-level issues. | | `not_executed` | The service was not reached, due to conditional policy logic or an earlier failure. | > **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](https://developer.alloy.com/public/reference/post_journeys-journey-token-applications-journey-application-token-rerun) 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](https://developer.alloy.com/public/reference/put_journeys-journey-token-applications-journey-application-token) endpoint. This status is generally avoidable by enforcing data validation before sending to Alloy. See [Data Validation](https://developer.alloy.com/public/docs/data-validation) for more details. ## Latency Alloy's Journey Application API endpoints and [webhooks](https://developer.alloy.com/public/docs/journey-events) return information about the [full status lifecycle of a Journey Application](https://developer.alloy.com/public/docs/application-statuses) in the `_embedded.events[]` array. Each event includes a `timestamp` field indicating when the event occurred in Unix time: ```json { "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. ### Diagnostics API for Timing and Latency For programmatic access to timing data without parsing the events array yourself, use the [Get Journey Application Timings](https://developer.alloy.com/public/reference/get_diagnostics-timings-journey-applications-journey-application-token) endpoint: `GET /v1/diagnostics/timings/journey-applications/{journey_application_token}` This returns: * Top-level metadata — `created_at`, `updated_at`, `closed_at`, and `duration_ms` for the journey application * An ordered `timeline_of_journey_application_events` array * Per-evaluation timing in `evaluations[]`, broken down by each service called during that evaluation, including individual outbound `api_requests` timings where available Example response (trimmed): ```json { "journey_application_token": "JA-mhjlfS6nZe1G6HuvAKVq", "created_at": 1725386185011, "closed_at": 1725386199876, "duration_ms": 14865, "evaluations": [ { "evaluation_token": "EV-4vX8jK2mN6bQeR9tYwLpZ", "duration_ms": 3500, "evaluation_status": "complete", "services": [ { "service_name": "Experian", "duration_ms": 1200, "api_requests": [ { "url": "https://api.experian.example.com/v1/lookup", "http_method": "POST", "duration_ms": 1200, "http_status": 200 } ] } ] } ] } ```