Redirects, Headers and Status Codes

Normally, the response includes an HTTP status code of 200, meaning "OK." Specifically, code 200 indicates that the URI refers to a valid resource, and that resource is included in the output of the response. Different circumstances call for different error codes. For example, if there was an error condition internal to the server that prevented the output of the intended data, the server can return a code of 500, meaning "Server error."

The request handler provides an error(...) method that prepares an error response with the given error code. For example:

class MyHandler(webapp.RequestHandler):
  def get(self):
    self.response.out.write("You asked me to do something.")
    try:
      doSomething()
      self.response.out.write("It's done!")

    except Error:
      # Clear output and return an error code.
      self.error(500)

The error(...) method takes a numeric HTTP status code, and prepares the request handler's response to use that status code. It also clears the output buffer, so the handler can prepare successful output using out then call error(...) later if there is a problem.

Another common use of status codes is to redirect the user's browser to a different URI. The redirection can be permanent, indicating the URI was once valid for the requested resource but all future requests for the resource should use the new URI. Or, the redirection can be temporary, indicating the requested URI is valid but the browser should request a different URI for now. A common technique for web applications is to use a temporary redirect in response to a successful form submission, preventing the user from accidentally using the browser's "back" button and re-submitting the form.

The request handler provides a redirect(...) method to prepare a redirect response. For example:

class FormHandler(webapp.RequestHandler):
  def post(self):
    if processFormData(self.request):
      self.redirect("/home")
    else:
      # Display the form, possibly with error messages.

redirect(...) takes the destination URI as its first parameter. By default, it establishes a temporary redirect. The optional argument permanent=True uses the permanent redirect code.

The request handler methods error(...) and redirect(...) change the HTTP status codes for the response. redirect(...) also uses an HTTP header to communicate the new URI to the client. The Response object provides methods for setting the status code and HTTP headers directly.

The response object's set_status(...) method changes the status code for the response. The method takes the numeric status code as its first parameter. An optional second parameter specifies a message to use instead of the default for the given status code.

The response object's headers property is a wsgiref.headers.Headers instance that represents the HTTP headers for the response. For information on how to set headers, see the wsgiref.headers documentation.

class StatusImageHandler(webapp.RequestHandler):
  def get(self):
    img_data = get_status_image_for_current_user()
    self.response.headers["Content-Type"] = "image/png"
    self.response.headers.add_header("Expires", "Thu, 01 Dec 1994 16:00:00 GMT")
    self.response.out.write(img_data)