Why am I getting a 401 HTTP status code?

Question

I'm getting a 401 in response to my request. What might be the problem?

Answer

First off, if you just created your security key and it's not working, give it at least 7 minutes for the authentication information to be distributed across our servers. If your key was made ages ago (longer than 10 minutes ago), read on...

A 401 code is specific to authentication- verifying that you are who you say you are. The process of authenticating your identity and obtaining permission to access our API is done using security keys. If you’re calling the API server-to-server, use the security keys shown (at the bottom of the Key Management page in your account). If you’re calling the API via an HTML request, you should use a Hostname and an Auth Token (see below, top).

Regarding the HTML call authentication method, improper formatting of the hostname produces most of the 401 responses that are called in for support. So what is the 'host'? This is simply the 'Referer' that’s found in the Network tab of your Developer Tools (F12 for Edge, Cmd + option + j for Chrome on Mac, Firebug if you’re using Firefox as your browser). Here are three examples of referrers and the different ways they can look:

1. This first example from www.bootbarn.com shows the referrer to be 'www.bootbarn.com'. In many cases, the referrer will follow the pattern 'www.websitename.com'. To find this 'referrer,' go to the page where your client enters their address information, then open the developer's tools (don't forget to go to this page, open the developer's tools, and refresh the page). This screenshot shows the developer tools in Chrome.
2. The next example shows that not all referrers will begin with the ubiquitous 'www'. This example is from knobsandhardware.com. The referer is 'knobsandhardware.atgstores.com'. Again, go to the page where the client enters the address to be verified, and check the developer's tools. This screenshot is from Firebug in Firefox.
3. The third example is from a fictitious site called score.com. The referrer is 'secure1.store.score.com'. This example illustrates that you must also include any subdomains.

It's worth noting that you may have several domains or 'referrers'. You may be calling from several pages on the site. We accommodate this by allowing you to create as many Auth Token/Host combinations as you need. If you’re super-tricky, you know you can also have several Host names on one single Auth Token. If you aren't sure how to do this, you can find out here. For more information on status errors, look through our HTTP status error documentation.

There is also a unique situation that generates a 401 when using embedded keys, server-side, over the cloud, or in a VPN. See more details here.

Fun fact

Did you notice how "Referrer" was spelled "Referer" in the HTTP header? This is a little humanizing typo from the genesis of the HTTP specification. You can read more about it on Wikipedia.