The "Fast Lane" Answer
A "status code" is a code that a computer or program gives regarding the functionality of a process. An "error code" is a status code that indicates something has prevented that process from executing as it normally would. Why use codes? Well, computers, as we've discussed in other places, really enjoy numbers and codes. They make keeping track of things easier. Things like whether or not processes are running smoothly.
The codes do at least two things: they help grease the wheels so that processes run better when things are working as they should, and they help in diagnostics and troubleshooting when things go wrong. They cover everything from "Did you understand that last transmission?" to "A circuit just fried as we were processing your request, so we can't give you what you asked for."
Without these codes, we'd have a hard time knowing when we had a problem, and an even harder time knowing what that problem was when we could figure out that something went wrong.
Your level of interaction with status and error codes may vary; often they're the sort of thing only handled by developers, programmers, and tech support. But if you're in any position to fiddle with something like an API, or even if you just want to understand why your web browser keeps giving you the number 404 instead of displaying the page you want, then the information below may prove helpful.
By the way, if you're wondering what error codes we provide with our API, you can find them down here.
The "Scenic Route" Answer
Police radio codes are a perfect example of how a system like status codes works. The radio codes, like status codes, are used both when things are operating smoothly and when things are going awry; they signify everything from "message received and understood" to "robbery in progress." They're a method of ensuring speed and effectiveness of communication.
Below is an illustration of a conversation between a police officer and police dispatch. We'll see a demonstration of how radio codes aid in the speed of communication, as well as message comprehension and the delivery of instructions. Let's take a look:
Officer McClaine is on duty one December evening, driving down a quiet street. His shift's been pretty peaceful so far, but that all changes when dispatch comes over the radio.
"Dispatch to Officer McClaine."
"Go for McClaine," he answers.
Dispatch repsonds, but the message is garbled due to poor reception.
"Uh, 10-9 Dispatch;" McClaine says, "I've got a 10-1 over here."
Dispatch tries again, and this time the message comes through clearer.
"We just got a 10-78 from Officer Fife; he's at a 211 in progress over on 5th and Main."
"5th and Main...Gordon or Callahan might be able to respond to that faster."
"Negative. Callahan and Gordon are both 10-7. You're the nearest unit that's 10-8."
"10-4," McClaine responds. "En route now."
"Roger that. 10-39, McClaine."
"10-4," he says again. Then, to himself, he smiles and says "Yippie ki yay."
McClaine switches on his lights and sirens as he flips his squad car around, and hits the gas.
The exchange between Dispatch and McClaine begins with Dispatch asking for McClaine's attention. He uses a common phrase to confirm they are speaking to him, that he is listening, and that the signal is (so far) going through properly. Next, when the signal breaks up and he can't understand their instructions, he asks them to repeat their message (10-9) on account of his poor reception (10-1).
What did all of this have to do with computer status and error codes? Everything. Once a proper connection is established, communication resumes and instructions are given (10-78—request for back up; 211—robbery). McClaine requests information of his fellow boys in blue (and why they're not responding instead of him). He's answered that they're off-duty or otherwise out of service (10-7), and that he's the only one around that's available and on-duty (10-8).
McClaine then confirms the instructions (10-4), and indicates his compliance. He is further instructed on how to respond to the robbery (10-39, respond with lights and sirens), and he confirms a second time before signaling the end of the exchange.
This is how computers operate. Everything from a process like adding "2+2", to devices communicating over the internet uses a system like this to make sure the job gets done.
Cracking the (Status) Code
There are two main applications you should be concerned with in regard to status codes. The first application is within a device's personal processes. The second is when a status code is used as two devices communicate with each other (like they might over a network or the internet). We'll start with the internal, then work our way to the external.
Executing a program starts with user input. You turn on a computer, you double-click a program, you enter data or commands. This tells the computer to execute—or run—a program, turning it into a process, and implementing the instructions that make up the program until the program is finally terminated (usually in the fulfillment of the command given to begin the whole process).
There are two things you need to know about running a process:
First, the routines within a process frequently call upon subroutines and the sub-subroutines thereof in order to get the job done. (This is much the way a police officer might call for a 10-78 (call for assistance), or how a contractor on a construction job will call in sub-contractors, who subsequently bring in their own crews to the worksite.)
Second, the process has to terminate itself in some fashion, otherwise it just goes on forever. Think of the scene from Fantasia when Mickey casts the spell and all the mops begin making a mess, continuing undeterred by any intervention, with no end in sight. That's a process that lacks a terminal off-switch.
We'll talk about the way programs resemble nesting dolls in a bit, as the process of dealing with an error code is tightly bound to it. For now, let's focus on our first status code, the exit code.
Exit Code: The Self-Terminator
As human beings, we walk away from tasks all the time before they're finished. Sometimes we take a break, sometimes we give up, sometimes we're interrupted. Chaucer's Canterbury Tales is fragments rather than a complete story, Mozart's Requiem was never finished, and as for this list —
Computers don't have the same limitations as we do. They don't need lunch breaks, or naps; they can't be interrupted by a "person from Porlock," and they don't get bored. So when we tell a computer to do something, we also have to give it conditions under which it can stop doing that thing. Here's what we mean.
"Tag" is an example of a game that has no win condition. Technically speaking, there's nothing in the rules explaining how to end the game. At what point do you stop, then? Well, if you're human, whenever everyone gets bored with it, or the bell rings and you have to go back to class. If you're a computer, though, there is no end. The only way to stop the process is to force it to stop, either by commanding the computer to abandon the process mid-thought, or by severing the flow of power to the device.
Chess, on the other hand, has a win condition. It also has non-victory end conditions that signal the end of the game in the event that it can't be won. There can be a checkmate, indicating a win. There can be a stalemate, indicating a draw. The losing player may have lost all pieces and then run out of moves. And of course, a player can concede to the other. All of these are things a computer can grasp, and translate into end conditions that can be used in a virtual chess match.
It can't, however, comprehend something like a player tossing the board in frustration.
All programs are this way. They need a "win condition," a way to tell when the job is accomplished and the mission completed. The parameters obviously differ depending on the purpose of the program, but the idea is the same. So computer systems are built with this in mind: they give the computer a way to end a process.
When the process ends, it produces a status code to explain which termination parameter it used. These are called "exit codes". Traditionally, "0" is the "win condition" code; in other words, if everything went according to plan, and the process ran without any problems, it gives "0" as its exit code.
It's a widely-accepted standard that any non-zero exit code indicates a problem (something like a "stalemate" or a table toss, if you will). This is an example of what an error code is, and perhaps the simplest one we can provide.
The error codes are usually tied to failure parameters that are set up when the program is written. Sometimes they're setup to match the conventions of other error code structures (like the HTTP error codes, for instance), but it's not always that user friendly, and often it requires knowing the setup specific to that program to know what they mean.
On some occasions, developers don't even bother putting a system together, leaving the error codes to mean about as much as the check engine light. Regardless of its clarity or effectiveness, exit codes tend to only mean one of two things: either "It worked," or "It didn't work, and this is the reason why."
Getting a Handle on Exception Handling
"Error code" is a somewhat vague term; they codify things that can be anticipated and controlled, as well as things that can't be helped. There's a word for all of these anomalies, if you will. They're called "exceptions" (short for "exceptional event"), and they include anything that disrupts the regular processes of a running program. Some are fatal (meaning they end the process entirely, resulting in a non-zero exit code), and some are not. Regardless of cause or fault, though, if they make it harder for the process to execute, it's an exception.
We bring this up because of a popular method for dealing with these exceptions. It's called "exception handling," and it's a helpful tool.
We've already mentioned that a program will call to additional processes in the course of execution. This descending train is called a "process chain," and typically the more advanced and complicated processes are at the top (they're the ones that received the original command, and they're the ones that called the others to work, so they're the ones running the show).
In order to get a "0" exit code, commands have to run the whole length of the process chain without encountering fatal errors (i.e., exceptions). But even if you get the right exit code, you might still end up with an error code indicating that the process completed, but not without incident. But how does a hiccup in the program translate into an error code that tells you what the problem is?
In exception handling, when a process hits an exception (read: anything out of the ordinary), it puts up a red flag. A separate, concurrent process is started with the purpose of finding a process that can deal with the exception. The exception is then "thrown"—the new process is given information on the exception, and then sent upward through the process chain looking for a process that can catalogue and test the error. If a process isn't equipped to deal with it, or can only partially handle the exception, it is thrown further up the chain.
Once a proper handler is found, the exception is sealed up in a little box for testing (that process is called "try/catch", fyi), and an error code is sent. A developer can then access the program, fiddle with the exception-in-a-box, then try and diagnose the issue.
"Go"-ing with an Alternative
Not every system used exception handling, though, and a notable example is the "Go" programming language. In Go, programs are designed to report the presence or absence of error codes by default. In other words, they essentially provide a visible status code with every run, whether or not there's an exception.
Each instruction (like, "Open this webpage" or "Calculate this formula") comes attached with a request for the error status of the process. Just like with error codes, if the value is 0, then have no fear, no error code is here (or there, rather). Any non-zero value means there's trouble, though even that's less than you might expect. Go processes rarely fail due to exceptions. It's a rare enough occurrence that they're not called "errors" when you have a fatal hiccup in Go; they're called "panics."
Error Code Causes
Error codes, and the exceptions that generate them, originate from three main areas:
- The side of the exchange that generates the request
- The side of the exchange that generates the response
- Bad luck
The "request side" origin (we might call this the "user" or "client," depending on the circumstance) means that something went wrong as the information was going in. Maybe you're asking for something that doesn't exist or isn't possible, like dividing by zero. Or maybe you entered it in the computer wrong (wrong spelling, wrong name, etc.), or the computer itself accidentally scrambled it before handing it off to the program. These are things that you (or your computer) had control over, but something still went wrong.
The "response side" (which can be the "server," "program," or other, depending on what you're doing) deals with giving you what you want. When you look up SmartyStreets.com on your web browser, you are the "request side," asking for the website. Our servers here in the office are the "response side," providing you with the web page you asked for. It's a response-side problem if our servers are too busy, or we don't support the HTTP version you're using. Things we could feasibly control fall under this category.
Then there's circumstance. Sometimes things break, or connection is lost, or a system glitches. When that's the case, it's just a straight up error. The response from both sides is "That's not supposed to happen." Under these circumstances, things can be as simple as plugging your internet router back in, or they can be as complicated as replacing a motherboard. In any case, you can't really blame a computer for what it can't control.
Examples of Status and Error Codes
Status and error codes (excluding the "0" exit code) tend to vary rather wildly, so the best examples we can give you are ones with an established system. And the most obvious system is HTTP. There is a standardized list of HTTP status and error codes, and it's a famous-enough list to prompt designing status codes of other programs and systems around that list. So without further ado, here's some highlights, both status and error, that might actually be worth knowing.
200—The Success Code
- Like a janitor doing his job, when this are working right, you don't even notice. The 200 status code is the one you want. It's equivalent to the police code "10-4"; the message from the client has been received, and understood, and the requested information is being supplied.
301—A Common Redirect
- Sometimes things on the internet move. Domain names change, IP addresses change, and no one likes moving without letting people know where you're going. A 301 status is essentially a forwarding address—it tells your computer that the address you're looking for has permanently moved, that its new location has been found, and that you're being redirected to it. There are similar codes for sites that have only been temporarily moved, among other things. They all resonate with the police code "10-6", which is an instruction to switch radio channels.
The following are error codes, with the 400s falling under the category of "client errors," and the 500s classifying as "server errors." Keep in mind, the general no-one's-fault errors are included, according to which side of the exchange they happened on.
- In police radio code, there's the "10-69" code, which means "message received." This is as opposed to "10-4", which means "message received and understood." A 400 bad request is kind of like that. The message went through, and the server received it, but it can't be answered because it doesn't know what it means. This is usually due to "bad syntax", meaning the client accidentally scrambled the message before it transmitted. The server can't do anything with gibberish, so it's asking the client to try again.
- The "You shall not pass" of the internet. It means you don't have clearance or authorization to access what you're looking for. If something is privacy protected, or requires some sort of security clearance, etc., you're going to be getting this error if don't have the correct permissions. Think of it as a "10-30": unauthorized radio use.
- Probably the one that's he most famous, 404 pops up whenever the server can't find what you're looking for. Maybe it doesn't exist. Maybe it moved and didn't tell anyone. Maybe it used to exist, but now it's gone the way of the Dodo. Or, perhaps you just put in the wrong URL. Whatever the reason, what you want is not where you thought was. It's kind of like getting on the radio and asking "What's your '20' (10-20)" to find out your buddy's location, and getting no response.
- This isn't like a sports timeout. In this case, it means someone had to wait too long. For a request timeout, that means that whatever instruction you gave your computer as a user didn't process fast enough, so only some or none of the information was sent to the server. Communication over TCP/IP is designed to have a shelf life, so that if a message is started but never finished, the receiving end has an exit code. Without it, they would be waiting forever. A request timeout is when the client started, but never finished, their request, so the server is letting you know "I was still listening; what happened?" Imagine it as the computer equivalent of the "10-9": repeat radio code.
414—Request-URI Too Long
- This one's easy. You put something too lengthy in the URL/search bar, and the server couldn't process it. Compare it to a "10-3": stop transmitting code.
415—Unsupported Media Type
- The server can't supply a response because you're asking for a format that it's not familiar with. They can't accommodate everybody and their dog, so you have to make it feasible for them. Compare it to a "10-10": negative.
500—Internal Server Error
- The first of the server errors. These are general glitches and technical problems, including not having enough memory/disk space. A 500 status code pretty much means something unexpectedly broke. Kind of like when your car breaks down for no reason (that's an 11-26, by the way).
- This is usually the result of the server being too busy due to heavy traffic. Kind of like overbooking a flight. Or a "10-6": busy code.
- Similar to a request timeout, gateway timeouts mean that, for whatever reason, the server couldn't get their act together fast enough, and the client had to wait too long. Most often this is due to the server needing additional information from upstream, and that server failed to send the information in rapid-enough succession. Think of it as a "10-85": arrival delayed.
505—HTTP Version Not Supported
- This one means that you're using a version of the protocol that's not supported by the server. Either you're too far ahead of the times, or too far behind, but in either case, proper communication can't be established because of this hurdle. This code is supposed to come with a list of supported HTTP versions. After all, it's not very helpful to know you don't have the right tool for the job, then be forced to guess which tool you actually need. Think of this as a "10-36": correct time check (because, you know, something's not "up to date").
Now, there's a category of statuses that merits a mention, since you're probably aware of them but never see the codes. They don't really have much in common, other than the fact that they translate the code into something a non-programmer can read. You've no doubt seen a few of them before. Here's an example or two.
Ever seen the dialogue box that pops up after a program crashes? "This program has closed unexpectedly, would you like to send an error report?" That means there was a non-zero exit code, and your computer knows what it means, but it's expecting that you, the user do not. So it translates it into something that's actually useful for you.
"The image did not load." Surely you've seen at some point the little broken jpeg symbol that happens when your internet connection scrambled a picture that was suppose to load on your browser. This is another example: you as a user don't need to know why the picture didn't load, so much as you need to know that you should reload the page to try and load it again.
"The computer did not shutdown properly." This could be the result of a computer crash, or loss of power, or maybe even a hard boot . In any case, the computer was forced to terminate all processes in a nonstandard fashion, and it's letting you know that it didn't care for that much.
Our API's Status and Error Codes
Our docs give a more indepth look at our status codes and what to do about them, but we felt like this was a good place to grab a snippet of what we have there, and mention it here for reference purposes. Below is the section on our error codes, which we've modeled after HTTP codes for simplicity:
Responses will have a status header with a numeric value. This value is what you should check for when writing code to parse the response. The only response body that should be read and parsed is a 200 response.
|Status Code||Responses and Explanation|
||Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.|
||Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.|
||Forbidden: (This most often occurs when trying to use our international service.) Because the international service is currently in a limited release phase, only approved accounts may access the service. Please contact us for your account to be granted access.|
||Bad Request (Malformed Payload): Inputs from the request could not be interpreted.|
Unprocessable Entity: A
||Too Many Requests: Too many requests with exactly the same input values were submitted within too short a period. This status code conveys that the input was not processed in order to prevent runaway charges caused by such condition as as a misbehaving (infinite) loop sending the same record over and over to the API. You're welcome.|
||Gateway Timeout: Our own upstream data provider did not respond in a timely fashion and the request failed. A serious, yet rare occurrence indeed.|
||OK (success!): A JSON array containing zero or more address matches for the input provided with the request. If none of the submitted addresses validate, the array will be empty ().|
What to Do About Errors
To end our discussion, let's talk about what to do with these codes. Success status codes only need the attention it takes to continue doing what you were already doing. But for error codes, sometimes the issue needs to be addressed. Some are issues that are one-time, self-addressing non-issues. But not all of them are.
- Hardware problems may require repair; if you have insufficient memory, or if something gets fried, it may take someone cracking open the device to get things running the way you want.
- If it's an input problem, the first step is to check your work. Make sure you didn't give the computer bad information, or a bad request. And try to avoid looking up pneumonoultramicroscopicsilicovolcanoconiosis.com.
- If you're having repetitive server problems, try calling tech support; the problem is on their end after all, so why not make them take care of it?
- Often, error code problems can be simply resolved by trying again—restarting the computer, restarting the program, refreshing the web page, etc; giving the computer a chance to start from scratch frequently frees up the capacity it needs to get the job done.
And with that, we've talked your ear off about status and error codes. Things can go wrong with computers, and they often do. But like any tool, computers are designed to be useful in spite of occasional-to-frequent hair-pulling complications. You may not know how to catch and try the error yourself, or what to do if your hard drive "cookies," but there's no shame in knowing when to hit the refresh button and when to call the Nerd Herd.
As long as you can get the problem fixed and get your work back on track, there's no need for your "error" to turn into "terror."
If you're looking for a more human illustration of all of this, have further questions about our API error codes, or need some technical assistance with our (or any, really) system dealing with an error code, feel free to call us. Our customer service "pit crew" is very tech savvy, and if they get stumped, they sit only ten paces from our industry experts. APIs and programming, this is what we do, so we're more than happy to help you make that call to Officer McClaine.