The purpose of this guide is to provide basic information for how to respond to an HTTP error code that you encounter while interacting with a web frontend. Although a lot of the techniques are generally applicable across any web interface, we will describe them in the context of using the Palantir platform.
When you try to open a webpage, your browser makes a series of requests to the server for the content of the page. The intent is that the server receives your requests, examines them to work out what content it should serve you, and then sends a response with the correct content. Your browser then pieces the content together to display the page.
This guide will dig into the concept of a request later, but here we are focusing on the response. Each response returned by the server will always include a status code. The status code denotes the status of the response the server is giving you. This is represented by a three-digit number, which has a corresponding meaning (usually defined by the Internet Engineering Task Force). You will probably have seen these when pages fail to load - terms such as "404" may be familiar to you. Here, we will dig a little more into what each code means and how you can use that information to find some easy fixes or better errors to report.
The first digit of the three-digit number that is sent in the response represents the category of status. The important categories for this guide are:
Now let's dive in to some actual codes. Note that this list is non-exhaustive, and if you encounter a number not listed here, you can reference the full list of HTTP status codes ↗.
This error message indicates that there was an internal issue with the request you sent to the server. Palantir developers work to ensure this error code is rarely encountered, as the most common cause is a malformed request syntax, which is usually defined in the underlying code. However, one common cause for a "Bad request" error is excessively large requests, where there is too much data in the request for the server to handle.
You will much more commonly see a "403 - Forbidden", in place of "401 - Unauthorized", however they are semantically very similar. Generally, a 401 error means your request was well-formed, but you are not authorized to make it. Where this differs from 403 is that it is usually reserved for when you have attempted to authorize yourself, but the authorization failed, or you have been flagged as "banned".
A Forbidden error indicates that you have made a request you are not permitted to make. You may encounter this error in the Palantir platform if there is an ACL (Access Control List) rule that says you are not allowed to access the resource you are trying to access. This may, for example, be some data that your user is not permitted to see, but it also applies to services. If your user is not permitted to access the Data Lineage application, for example, you may see a "403 - Forbidden" when you try to do so.
This error means you have requested something that does not exist. For example, if a specific asset was removed, accessing that asset would be represented as a "404 - Not Found", because the resource you have requested does not exist.
This error signifies that the server received the request and needed to perform an internal operation to generate the response. However, an internal error occurred within the server during this process.
For example, suppose your server's job is to take a request containing two numbers, and then divide the first number by the second. In this example, if you send a request to the server with the numbers "8" and "2", it will return a response with status code 200 (success) and the response will contain the answer "4". However, if you send "5" and "0", you may see "500 - Internal Server Error", because when the server tried to compute 5/0, it caused an error internally. In the context of the Palantir platform, this means you need to look at the internals of the service concerned in order to work out what error was occurring internally. This usually means identifying the service and looking for relevant logs, which we will cover later in this guide.
The term "Gateway" refers to the fact that there is an element of "indirection" behind the scenes in the connection between services. Suppose you get this error when trying to open https://foundry.link/workspace/magic-app. What actually happens is that your request hits a single server (the "Gateway" server), and then the gateway server passes your request onward. Notably, magic-app is probably running on a different server than the gateway, so the gateway has to ask that server (called "upstream server") for the response, intending to give that response back to you. This error means that the upstream server gave an invalid response.
This error indicates that the service exists because otherwise a 404 error would have been received. However, the service was unable to process your request, most commonly due to being down or overloaded. For example, if Contour has too many requests and simply cannot handle any further requests, you may get a "503 - Service Unavailable". This could be due to not enough computation resources or due to an internal bug, for example, a memory leak.
This error is similar to "502 - Bad Gateway", except that the gateway server made a correct request, and did not receive a timely response from the upstream server. This can happen for a variety of reasons, including problems with the network connection, server downtime, or a server overload. When a 504 error occurs, it usually means that the website or web application you are trying to access is temporarily unavailable. It is not typically a problem with your own device or internet connection.