跳转至

Understand HTTP Error Codes（理解 HTTP 错误代码）

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.

What are HTTP error codes?

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:

  • 2xx: If the code begins with a 2, then the request was successful. The full code will usually simply be 200, which represents a generalized successful request and response.
  • 4xx: If the code begins with a 4, then the request was unsuccessful due to a client error. The client refers to the entity making the request, usually the browser or webpage that you are using at the time. We will see some examples of these codes below.
  • 5xx: If the code begins with a 5, then the request was unsuccessful due to a server error. This usually means your request was well-formed and well-made, but when the server examined it and tried to work out what response to send back, something went wrong. We will see some examples of these codes below.

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 ↗.

Client error

400 - Bad request

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.

Return to top

401 - Unauthorized

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".

Return to top

403 - Forbidden

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.

Return to top

404 - Not found

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.

Server error codes

500 - Internal server error

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.

Return to top

502 - Bad gateway

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.

Return to top

503 - Service unavailable

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.

Return to top

504 - Gateway timeout

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.

Return to top

中文翻译

理解 HTTP 错误代码

本指南旨在提供基本信息，帮助您了解在操作 Web 前端时遇到 HTTP 错误代码时应如何应对。虽然许多技术方法普遍适用于各种 Web 界面，但我们将在 Palantir 平台的上下文中进行说明。

什么是 HTTP 错误代码？

当您尝试打开一个网页时，您的浏览器会向服务器发送一系列请求以获取页面内容。其流程是：服务器接收您的请求，检查请求以确定应提供哪些内容，然后发送包含正确内容的响应。您的浏览器随后将这些内容拼合起来，以显示页面。

本指南稍后会深入探讨请求的概念，但这里我们重点关注响应。服务器返回的每个响应都会包含一个状态码(Status Code)。状态码表示服务器给您的响应状态。它由一个三位数字表示，每个数字都有相应的含义（通常由互联网工程任务组定义）。当页面加载失败时，您可能见过这些状态码——例如"404"这样的术语可能对您来说并不陌生。在这里，我们将进一步探讨每个代码的含义，以及如何利用这些信息找到简单的解决方法或更准确的错误报告。

响应中发送的三位数字的第一位代表状态类别。本指南中重要的类别包括：

  • 2xx：如果代码以 2 开头，则表示请求成功。完整的代码通常只是 200，代表一个通用的成功请求和响应。
  • 4xx：如果代码以 4 开头，则表示由于客户端错误(Client Error)导致请求失败。客户端指的是发起请求的实体，通常是您当时使用的浏览器或网页。下面我们将看到一些此类代码的示例。
  • 5xx：如果代码以 5 开头，则表示由于服务器错误(Server Error)导致请求失败。这通常意味着您的请求格式正确且构建良好，但当服务器检查请求并试图确定应返回什么响应时，出现了问题。下面我们将看到一些此类代码的示例。

现在让我们深入了解一些具体的代码。请注意，此列表并非详尽无遗，如果您遇到此处未列出的代码，可以参考 HTTP 状态码完整列表 ↗。

客户端错误

400 - 错误请求

此错误消息表示您发送给服务器的请求存在内部问题。Palantir 的开发人员致力于确保此错误代码很少出现，因为最常见的原因是请求语法格式错误，而这通常由底层代码定义。然而，"错误请求"的一个常见原因是请求过大，即请求中包含的数据过多，服务器无法处理。

返回顶部

401 - 未授权

您更常见到的是"403 - 禁止访问"，而不是"401 - 未授权"，但它们在语义上非常相似。通常，401 错误意味着您的请求格式正确，但您没有权限发起该请求。它与 403 的区别在于，401 通常用于您尝试进行身份验证但验证失败，或者您已被标记为"禁止"的情况。

返回顶部

403 - 禁止访问

禁止访问错误表示您发起了不被允许的请求。在 Palantir 平台中，如果存在 ACL（访问控制列表）规则规定您无权访问您正在尝试访问的资源，您可能会遇到此错误。例如，这可能是一些您的用户无权查看的数据，但它也适用于服务。例如，如果您的用户无权访问数据沿袭(Data Lineage)应用程序，当您尝试访问时，可能会看到"403 - 禁止访问"。

返回顶部

404 - 未找到

此错误表示您请求的内容不存在。例如，如果某个特定资产已被移除，访问该资产时就会显示"404 - 未找到"，因为您请求的资源不存在。

服务器错误代码

500 - 内部服务器错误

此错误表示服务器收到了请求，并且需要执行内部操作来生成响应。但是，在此过程中服务器内部发生了错误。

例如，假设您的服务器的工作是接收一个包含两个数字的请求，然后用第一个数字除以第二个数字。在这个例子中，如果您向服务器发送包含数字"8"和"2"的请求，它将返回状态码 200（成功）的响应，并且响应中包含答案"4"。但是，如果您发送"5"和"0"，您可能会看到"500 - 内部服务器错误"，因为当服务器尝试计算 5/0 时，内部发生了错误。在 Palantir 平台的上下文中，这意味着您需要查看相关服务的内部情况，以确定内部发生了什么错误。

返回顶部

502 - 错误网关

术语"网关"指的是在服务之间的连接背后存在一个"间接"元素。假设您在尝试打开 https://foundry.link/workspace/magic-app 时遇到此错误。实际发生的情况是，您的请求首先到达一个服务器（"网关"服务器），然后网关服务器将您的请求转发出去。值得注意的是，magic-app 可能运行在与网关不同的服务器上，因此网关必须向该服务器（称为"上游服务器"）请求响应，意图将该响应返回给您。此错误意味着上游服务器给出了无效的响应。

返回顶部

503 - 服务不可用

此错误表示服务是存在的，否则您会收到 404 错误。但是，该服务无法处理您的请求，最常见的原因是服务宕机或过载。例如，如果 Contour 收到太多请求，根本无法处理更多请求，您可能会收到"503 - 服务不可用"。这可能是由于计算资源不足，或者由于内部错误（例如内存泄漏）导致的。

返回顶部

504 - 网关超时

此错误与"502 - 错误网关"类似，区别在于网关服务器发出了正确的请求，但没有及时收到上游服务器的响应。这可能是由多种原因造成的，包括网络连接问题、服务器宕机或服务器过载。当出现 504 错误时，通常意味着您尝试访问的网站或 Web 应用程序暂时不可用。这通常不是您自己的设备或互联网连接的问题。

返回顶部