Designing Resilient Verification: Handling Timeout Scenarios in Multi-Service Workflows

When building identity verification pipelines, the goal is often to gather as much context as possible about a user's presence across platforms. Using the Combo Check API allows you to query multiple services—like WhatsApp, Telegram, and VK—in a single request. However, distributed systems are rarely perfect. A common challenge arises when one service within a multi-service request experiences a transient delay, resulting in a partial response.

The Anatomy of a Partial Result

The Combo Check API is designed to return a consolidated response even if individual service checks encounter issues. When you submit an identifier to POST /v1/check/combo/phone, the API processes your requested service_types in parallel.

If a specific service fails to respond within the internal processing window, the API returns a timeout error for that specific node in the data.results object. Crucially, the overall API call remains successful (HTTP 200), and you receive the valid, completed signals for the other services in the same payload.

Example Response with Timeout

{
 "data": {
 "results": {
 "ws": { "registered": true, "error": null },
 "vk": { "registered": null, "error": "timeout" }
 }
 }
}

Implementation: Conditional Retry Strategy

To ensure your application remains resilient, you should implement a handler that inspects the data.results object for any error fields. Rather than discarding the entire transaction, you can isolate the failed service and perform a targeted retry.

Step-by-Step Handling Logic

1. Parse the Response: Iterate through the data.results object.
2. Identify Failures: Check if any service node contains an error field with the value "timeout".
3. Isolate and Retry: For services that timed out, trigger a follow-up request using the dedicated POST /v1/check endpoint. This allows you to fetch the missing signal without re-billing or re-querying the services that already returned a valid result.
4. Update State: Merge the result from the single-check retry into your local user identity record.

Testing and Sandboxing

Before deploying your retry logic, it is essential to validate how your system handles these partial states.

• Create Fixture Files: Generate local JSON files that mimic the structure of a partial response, specifically including the error: "timeout" field.
• Contract Testing: Use these fixtures to ensure your parser correctly identifies the timeout and triggers the secondary POST /v1/check call.
• Timeout Simulation: Configure your client-side timeout to at least 15s to ensure you allow the API enough time to complete its internal parallel execution before your application layer prematurely terminates the connection.

Conclusion

Resilience in identity workflows is about gracefully handling the reality of distributed service availability. By treating the Combo Check API as a provider of individual signals—some of which may require a secondary attempt—you can build a more robust verification layer. For more details on integrating these checks, refer to the official documentation.

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