{"templateId":"markdown","sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":["typography","box","badge"]},"redocly_category":"Articles","type":"markdown"},"seo":{"title":"Talking timeouts","description":"In software development, timeouts are a necessary evil - a choice to inflict minor pain on client code in order to avoid something worse. Although simple to apply, their impact on service quality means that they require careful thought.","siteUrl":"https://docs.worldpay.com/access","image":"/access/assets/worldpay-logo-light.21b7daf79984773a9fcd7d4fbcb07ae5289dfffd6023c4c3dca720c7058e53dc.33f780a6.svg","keywords":"documentation, api, openapi, sdks, developer, payments, json, payouts, 3ds","jsonLd":{"@context":"https://schema.org","@type":"Organization","url":"https://docs.worldpay.com/access","name":"Worldpay"},"meta":[{"name":"google-site-verification","content":"zjziIKaP3ImsqsfhYnEBnq1R85UabiSwl7HTXuwtZuo"},{"name":"doc_product","content":"Access"},{"name":"doc_category","content":"Documentation"}],"llmstxt":{"hide":false,"sections":[{"title":"Payments API","description":"Payment orchestration API combining fraud assessment, 3ds authentication, SCA exemptions, Worldpay Token creation and a card or wallet based payment.","includeFiles":["products/payments/@20240601/**/*"],"excludeFiles":[]},{"title":"Payment Queries API","description":"Querying your payments data, based on a variety of parameters.","includeFiles":["products/payment-queries/@v1/**/*"],"excludeFiles":[]},{"title":"Card BIN Data API","description":"Provides detailed information about a card.","includeFiles":["products/card-bin/@v1/**/*"],"excludeFiles":[]},{"title":"3DS Authentication API","description":"Request 3DS authentication to protect against fraud, be SCA compliant and to shift liability using this standalone API.","includeFiles":["products/3ds/@v3/**/*"],"excludeFiles":[]},{"title":"FraudSight API","description":"Request a risk assessment and receive a response with an outcome (e.g. lowRisk) using this standalone API.","includeFiles":["products/fraudsight/@v1/**/*"],"excludeFiles":[]},{"title":"Checkout SDK","description":"Integrate using our clientside SDKs for both web and native devices. Benefit from SAQ-A/PCI-SSF compliance.","includeFiles":["products/checkout/web/@v2/**/*","products/checkout/ios/@v4/**/*","products/checkout/android/@v4/**/*","products/checkout/react-native/@v3/**/*","products/checkout/flutter/@v1/**/*"],"excludeFiles":[]},{"title":"Tokens API","description":"Minimizes the exposure of sensitive card details and increases the security of your customer's card details.","includeFiles":["products/tokens/@v3/**/*"],"excludeFiles":[]},{"title":"Card Payments API","description":"Request a card payment using this standalone API, requires separate requests for 3DS, Fraud assessment etc.","includeFiles":["products/card-payments/@v7/**/*"],"excludeFiles":[]},{"title":"Card Verifications API","description":"Verify your customer's card to maximize your authentication rates.","includeFiles":["products/card-verifications/@v6/**/*"],"excludeFiles":[]},{"title":"Account Payouts API","description":"Send funds to your customer's bank accounts and search for payouts using parameters.","includeFiles":["products/account-payouts/@20250101/**/*"],"excludeFiles":[]},{"title":"APMs","description":"Pay using eWallets, bank transfers, direct debits, local card schemes, Postpay and eInvoice/ Buy Now Pay Later.","includeFiles":["products/apms/@20240701/**/*"],"excludeFiles":[]},{"title":"Balance API","description":"Request your account details for a single account or all accounts under an entity.","includeFiles":["products/balance/@20250101/**/*"],"excludeFiles":[]},{"title":"Card Payouts API","description":"Send funds to your customer's cards.","includeFiles":["products/card-payouts/@v4/**/*"],"excludeFiles":[]},{"title":"Events (Webhooks)","description":"Receive status updates from Access Worldpay by setting up a webhook.","includeFiles":["products/events/@v1/**/*"],"excludeFiles":[]},{"title":"FX API","description":"Manage Foreign Exchange (FX) on your payments.","includeFiles":["products/fx/@v1/**/*"],"excludeFiles":[]},{"title":"Hosted Payment Pages (HPP) API","description":"Our low-code option to take payments securely at the lowest PCI compliance level - SAQ A.","includeFiles":["products/hosted-payment-pages/@v1/**/*"],"excludeFiles":[]},{"title":"Money Transfers API","description":"Money Transfer OCTs (Original Credit Transaction) allow funds to be pushed to an eligible card in 30 minutes or less.","includeFiles":["products/money-transfers/@v1/**/*"],"excludeFiles":[]},{"title":"Parties API","description":"Create parties, manage your payout instruments and beneficial owners and carry out identity verification checks.","includeFiles":["products/parties/@20250101/**/*"],"excludeFiles":[]},{"title":"SCA Exemptions API","description":"Maximize a frictionless checkout experience by using issuer data insights to apply exemptions.","includeFiles":["products/sca-exemptions/@v1/**/*"],"excludeFiles":[]},{"title":"Split Payments API","description":"Divide funds from a single payment amongst yourself and your parties/sellers.","includeFiles":["products/split-payments/@20250625/**/*"],"excludeFiles":[]},{"title":"Statements API","description":"Retrieve your account statement and see individual entries for all credits and debits.","includeFiles":["products/statements/@20250101/**/*"],"excludeFiles":[]},{"title":"Transfers API","description":"Transfer funds from source account to target account.","includeFiles":["products/transfers/@20250101/**/*"],"excludeFiles":[]},{"title":"Verified Tokens API","description":"Verified Tokens ensures that your customer's payment details are valid and CIT compliant when creating a token.","includeFiles":["products/verified-tokens/@v3/**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Typography","attributes":{"fontSize":"1.2em","as":"div"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/articles"},"children":["← Back to articles list"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"talking-timeouts","__idx":0},"children":["Talking timeouts"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"the-what-the-why-the-how--the-when","__idx":1},"children":["The what, the why, the how & the when."]},{"$$mdtype":"Tag","name":"Box","attributes":{"display":"inline-flex","gridTemplateColumns":["1fr 1fr","1fr 1fr 1fr","1fr 1fr 1fr"],"gridGap":"1rem","mt":"1rem","mb":"1rem"},"children":[{"$$mdtype":"Tag","name":"Badge","attributes":{"size":"small","fontWeight":"bold","color":"white","mt":"0rem","mb":"0.5rem","px":"1rem","py":"0.5rem","borderRadius":"6rem","bg":"var(--wp-colour-light-blue)"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Technical"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Written by ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Andy Brodie"]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","04 August 2020"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Timeouts. In software development, they're a necessary evil - a choice to inflict minor pain on client code in order to avoid something worse. Although simple to apply, their impact on service quality means that they require careful thought. In this article, Andy Brodie explains timeouts and outlines five principles to help set them effectively when writing clients to web services, such as Access Worldpay."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Whether you're a developer, a customer or just a member of the public, you'll have experienced timeouts. They play a key role in building robust web service clients, such as to our Payments, Wallets or Fraudsight services. When all's going well, it's like they aren't there - your client code makes a request, the service responds quickly and tells you whether the request succeeded or failed."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If there's a problem, though, their existence becomes all too apparent. Your code times out - simply because it's decided that it's better to not know the outcome than be kept on hold for any longer, waiting to find out."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"no-harm-done","__idx":2},"children":["No harm done?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["How big a deal this is depends on the nature of the original request. If it's something that doesn't involve any changes to the state of the web service, then the client code can simply try again after a period of time. No harm done."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It's a different story when the request involves an operation such as a payment sale, which both authorizes a payment and initiates a settlement. Clearly, success or failure impacts the state of the service (and beyond) - it's important to know whether the sale did or didn't happen before making the same request again and risking a second, duplicate sale."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reconciliation-required","__idx":3},"children":["Reconciliation required"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In situations like this, you need to consider how to reconcile the state of the client and also the state of the service, along with the ensuing complexity. For example, you may need to execute a query against the service to discover the outcome that you missed because of the timeout and only then decide whether to proceed with a retry."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["That's a simple example, though - the complexity increases exponentially with the number of reconciliation operations each timeout requires. In other words, for every operation that timed out, you must also resolve all the failure cases for all the reconciliation operations."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-do-requests-time-out-anyway","__idx":4},"children":["Why do requests time out, anyway?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Given all this complexity, it's reasonable to ask: why do timeouts happen at all? There are two main reasons:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Packet drops or mis-routing - when packets of data don't reach their destination, either to the service or back to the client. These failures affect single requests and seem random. Because they're so short and unpredictable, they're typically very hard to diagnose but are often caused by faulty network components."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A service problem - the service might be experiencing unusually heavy load or a problem with a downstream dependency and can't therefore respond to the request as quickly as necessary."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A single failure, such as one caused by a packet drop, usually makes reconciliation straightforward. You discover the state of the service, reconcile it with the state of the client and carry on as before."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Life becomes more complicated with a service problem. For instance, if the original request timed out because of a service overload, there's a chance that your follow-up reconciliation operations will also time out."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-do-clients-need-timeouts","__idx":5},"children":["Why do clients need timeouts?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When configuring client code, there are good reasons to include timeouts. They're usually included to protect the client from performance issues or from resource starvation."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Performance issues: in these situations, the service shouldn't rush to time out and leave the client code not knowing what happened. If timing out is the only way to free up the client to do something else, then consider decoupling the client's response to its customer from the response it is waiting for itself from the service (see service chains, below)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Resource starvation: If this client code is processing lots of concurrent requests and volume is ramping up, then you don't want it consuming large amounts of memory, CPU or I/O resources. Techniques such as asynchronous I/O can help minimize the overheads of each call, enabling you to safely wait longer for a reply."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"five-key-principles","__idx":6},"children":["Five key principles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Given how impactful timeouts can be, it's important to think carefully before setting their parameters. We've identified five principles to help achieve the best possible outcome in web service clients."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-prioritize-service-quality","__idx":7},"children":["1. Prioritize service quality"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Think first about the availability, latency or cost of the service. A process should only time out if that damages service quality less than the alternative - in other words, if not knowing the outcome of the process is better than waiting any longer for that process to finish. Different operations will, therefore, need different timeout parameters. Operations with no side effects, or idempotent requests, can afford to have more aggressive timeouts because retrying them has no side effects."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an operation does time out, it must have a pre-defined recovery and reconciliation procedure - in other words, code that reconciles the view of the service with the view of the client code."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-mind-your-slas","__idx":8},"children":["2. Mind your SLAs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Many services specify a maximum latency in the Service Level Agreement (SLA): \"This service will respond in 900ms\", for example. In this example, if the service responds after 900ms then it's considered unavailable from an SLA perspective, regardless of the response itself."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Should a client time out with the service before the SLA has been breached, the client is unavailable, not the service."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-dont-be-rigid","__idx":9},"children":["3. Don't be rigid"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The period after which a client times out should be a function of resource consumption and availability. Therefore, it needs to be flexible. A client experiencing a very low load may be able to afford to time out after a few minutes; one with a very high load may time out much faster. For example, if most requests complete in less than a second, it may time out after just a few seconds."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Clients are expected to look after their own best interests; the service cannot be expected to do this for them. They should, therefore, adopt the principle that they will wait for a response to their request up to the point at which this impacts their own effectiveness. Once they reach this point, they should time out."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-you-can-break-a-service-chain","__idx":10},"children":["4. You can break a service chain"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are often chains of service requests within a service architecture. For example: Client X calls Service A, which itself is a client to Service B. If Client X times out waiting for Service A because Service A is awaiting a response from Service B, this doesn't mean that Service A should time out waiting for Service B."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Instead, Service A should wait as long as it can to find out whether or not the operation completed so it can be reported, logged or stored as appropriate. In this way, when Client X comes back to Service A asking what happened, it gets the answer without any need for a subsequent reconciliation between Service A and Service B."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"5-avoid-too-much-repetition","__idx":11},"children":["5. Avoid too much repetition"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Timeouts aren't very helpful if they just keep on happening - i.e. when every request fails. To avoid this, you should set your parameters to maximize the number of successful requests. If a process sees a sustained slowdown on a service that is causing repeated timeouts, it should consider how to increase the timeout period without jeopardizing its own stability. For example:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["it could process fewer requests concurrently;"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["it could prioritize this process by degrading another part of the client;"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["it could give up give up on the service entirely for a specified period and try later in the expectation that the service's latency may, by then, have regained its normal level."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"finding-a-balance","__idx":12},"children":["Finding a balance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By their very nature, timeouts are a blunt solution to a bad situation. As a result, they need to be considered with care and then configured so as to avoid causing problems that are bigger than those they're intended to solve. I hope that this article and the principles we've established at Access Worldpay will help you find the right balance for your own web service clients - one that achieves the best possible outcomes for your customers."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"b","attributes":{},"children":["Andy Brodie is Senior Product Manager for Quality of Service at Access Worldpay. "]}]}]},"headings":[{"value":"Talking timeouts","id":"talking-timeouts","depth":1},{"value":"The what, the why, the how & the when.","id":"the-what-the-why-the-how--the-when","depth":3},{"value":"No harm done?","id":"no-harm-done","depth":2},{"value":"Reconciliation required","id":"reconciliation-required","depth":2},{"value":"Why do requests time out, anyway?","id":"why-do-requests-time-out-anyway","depth":2},{"value":"Why do clients need timeouts?","id":"why-do-clients-need-timeouts","depth":2},{"value":"Five key principles","id":"five-key-principles","depth":2},{"value":"1. Prioritize service quality","id":"1-prioritize-service-quality","depth":3},{"value":"2. Mind your SLAs","id":"2-mind-your-slas","depth":3},{"value":"3. Don't be rigid","id":"3-dont-be-rigid","depth":3},{"value":"4. You can break a service chain","id":"4-you-can-break-a-service-chain","depth":3},{"value":"5. Avoid too much repetition","id":"5-avoid-too-much-repetition","depth":3},{"value":"Finding a balance","id":"finding-a-balance","depth":2}],"frontmatter":{"seo":{"title":"Talking timeouts","description":"In software development, timeouts are a necessary evil - a choice to inflict minor pain on client code in order to avoid something worse. Although simple to apply, their impact on service quality means that they require careful thought."},"markdown":{"toc":{"hide":true}}},"lastModified":"2025-10-28T16:40:42.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/articles/timeouts","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}