« back to the getting started docs

Timeouts and other network jazz

Face it, at some point or another, the API calls you are making will fail. It could be something completely outside of your control like your internet connection failing or the service provider you're connecting to going down or being under heavy load. It happens.

Or, it could be because you don't quite understand enough about what's going on behind the scenes of the code or wrapper your are building on top of. So let's quickly cover some basics that any code making network connections handles at some point and the few things you may need to worry about. These are in order of your likelihood of running into them, not the order they actually happen during a call.

One final point as you'll see: Stream Timeouts and Connection Timeouts are completely different beasts, imply completely different things, and should be set completely differently.

Stream Timeouts

A stream timeout comes into play once your code has successfully made a network socket connection to the remote host and you are in the middle of sending receiving data. The timeout occurs because the network code handling that connection has a hard limit set on how long it is allowed to pass data back and forth. The tricky part here is that unless you know better, you're never going to have to set this - there's a default value being set somewhere. Often in core network libraries it's around 30 seconds - we happen to default our wrappers to 300 seconds (5 minutes).

For calls that are supposed to be really short and should finish quickly, you'll won't notice an issue - until the service you are connecting to is under heavy load and some of those calls you expected to take 1 - 2 seconds all of a sudden start taking upwards of 5, 10, or even 30 seconds. You know what happens then? Well, that call will generally keep happily churning away on that service's servers - but your client library just tore down the connection and didn't return anything. No error occurred and for all you know everything completed correctly and the service tried to return some important data to you. But you - you got nothing.

So, know your stream timeouts. A few points:

• If your library supports a timeout value, it is likely this.
• Look at how long the calls you are making typically take, then bump your timeouts up to several times that to protect against missing data.
• Running short and long calls - get to know your library and set timeouts differently based on what your code is doing
• Can't handle a slow API call during a page load? Don't run them inline - queue those things up and run them in the background later. Yeah, that can be a hassle, but you can't always have your cake and eat it too
• Finally, as mentioned initially, your calls will fail at some point. Prepare your code and processes for that. Seriously, it's going to happen

Connection Timeouts

Connection timeouts refer to actually setting up the aformentioned network socket connection and occur without you ever having a chance to send or receive data. From a failure stance, these can be more bearable since you know the call was not completed (or even started), so it's simple enough to retry the call later. As mentioned above, though, if you are running things inline while loading a page, you may have very specific requirements about how much of a delay there can be in the case of failure. In other words, you may want to set your connection timeouts low (based on the info below). Background processes don't care, so leave'em where they are to have the best chance of a call completing.

Connection timeouts typically happen in one of these scenarios:

• High network latency. This could be related to being on a saturated network, your ISP being overloaded, the service's network being overloaded, or any blockages in between. This is a reason to leave them a bit higher.
• Other network service issues such as really slow DNS requests since that will be part of making the connection
• Extremely high load on the servers at a service provider (aside from general network saturation).

So that can be a little tricky to tweak. Typically it's best to leave these at their defaults and, as above, just be prepared to deal with it happening eventually. In our MCAPI PHP wrapper we set the connection timeout to 30 seconds to attempt to cover any situation, though even that may be a bit high.