Handling Partial Results in Multi-Service Verification Flows

When building identity verification workflows, reliability often hinges on how your application handles non-deterministic outcomes. In a multi-service architecture, such as when using the Combo Check API, you might encounter scenarios where some service nodes return valid registration signals while others return errors due to timeouts.

This guide covers how to architect your integration to parse these partial results effectively.

Understanding the Combo Check Response

The Combo Check API allows you to verify a single identifier against multiple services in one request. Because these checks run in parallel, the API returns a consolidated JSON object. A critical detail for developers is that individual service failures do not cause the entire API call to fail.

When a service fails to return a result within the processing window, it returns an error field (e.g., "timeout") and sets the registered field to null.

Parsing the Response Structure

Your application logic should iterate through the data.results object rather than expecting a uniform response across all requested services. Here is a conceptual approach to mapping these results:

// Conceptual logic for processing the API response
function processComboResults(apiResponse) {
 const results = apiResponse.data.results;

 for (const [service, outcome] of Object.entries(results)) {
 if (outcome.error) {
 console.warn(`Service ${service} failed: ${outcome.error}`);
 // Handle the timeout: log for retry or flag for manual review
 continue;
 }

 if (outcome.registered === null) {
 console.log(`Service ${service} could not determine registration status.`);
 } else {
 console.log(`Service ${service} registered: ${outcome.registered}`);
 }
 }
}

Implementation Checklist

1. Set Client Timeouts: Ensure your HTTP client is configured with a timeout of at least 15 seconds. This provides enough headroom for the API to process parallel requests and return the status of successful checks even if others time out.
2. Verify Billing Logic: Note that only determined results are billed. The API response provides a billed_count and total_cost_usd field, allowing you to reconcile costs per service-specific execution.
3. Implement Individual Retries: If a service returns a timeout error, you do not need to re-run the entire combo. You can isolate the failed service and retry it individually using the /v1/check endpoint.
4. Handle Null States: Always check for null in the registered field. A null value indicates that the service was unable to verify the identifier, which is distinct from a false (not registered) or true (registered) result.

Conclusion

By treating the Combo Check response as a collection of independent service outcomes, you can build a more resilient verification layer. Instead of failing the entire process due to a single service timeout, focus on extracting the available signals and implementing targeted retries for the specific services that failed to respond.

This article was drafted with AI assistance and reviewed before publishing.

---

Read the eKYC Pro API docs