How Requests are Handled

This document describes how your application should serve and respond to requests.


  1. Serving requests
  2. Request headers
  3. Responses
  4. Quotas and limits

Serving requests

Your application is responsible for starting a webserver and handling requests. You can use any web framework that’s available for your development language.

App Engine runs multiple instances of your application, each instance has its own web server for handling requests. Any request can be routed to any instance, so consecutive requests from the same user are not necessarily sent to the same instance. An instance can handle multiple requests concurrently. The number of instances can be adjusted automatically as traffic changes.

Request headers

An incoming HTTP request includes the HTTP headers sent by the client. For security purposes, some headers are sanitized or amended by intermediate proxies before they reach the application.

The following headers are removed from the request:

  • Accept-Encoding
  • Connection
  • Keep-Alive
  • Proxy-Authorization
  • TE
  • Trailer
  • Transfer-Encoding

In addition, the header Strict-Transport-Security is removed from requests served to any domains other than or *

These headers relate to the transfer of the HTTP data between the client and server, and are transparent to the application. For example, the server can automatically send a gzipped response, depending on the value of the Accept-Encoding request header. The application itself does not need to know which content encodings the client can accept.

App Engine specific headers

As a service to the app, App Engine adds the following headers to all requests:

Country from which the request originated, as an ISO 3166-1 alpha-2 country code. App Engine determines this code from the client's IP address. Note that the country information is not derived from the WHOIS database; it's possible that an IP address with country information in the WHOIS database will not have country information in the X-AppEngine-Country header. Your application should handle the special country code ZZ (unknown country).
Name of region from which the request originated. This value only makes sense in the context of the country in X-AppEngine-Country. For example, if the country is "US" and the region is "ca", that "ca" means "California", not Canada. The complete list of valid region values is found in the ISO-3166-2 standard.
Name of the city from which the request originated. For example, a request from the city of Mountain View might have the header value mountain view. There is no canonical list of valid values for this header.
Latitude and longitude of the city from which the request originated. This string might look like "37.386051,-122.083851" for a request from Mountain View.

App Engine services might add additional request headers:

Requests from the Cron Service will also contain a HTTP header:

X-AppEngine-Cron: true

See Securing URLs for cron for more details.

Requests coming from App Engine applications running in a App Engine standard environment that use the URLFetch API will include a header identifying the app making the request:



App Engine calls the handler with a Request and a ResponseWriter, then waits for the handler to write to the ResponseWriter and return. When the handler returns, the data in the ResponseWriter's internal buffer is sent to the user.

This is practically the same as when writing normal Go programs that use the http package.

As explained below, there are limits that apply to the response you generate, and the response may be modified before it is returned to the client.

Streaming Responses

App Engine does not support streaming responses where data is sent in incremental chunks to the client while a request is being processed. All data from your code is collected as described above and sent as a single HTTP response.

Response compression

If the client sends HTTP headers with the original request indicating that the client can accept compressed (gzipped) content, App Engine compresses the handler response data automatically and attaches the appropriate response headers. It uses both the Accept-Encoding and User-Agent request headers to determine if the client can reliably receive compressed responses.

Custom clients can indicate that they are able to receive compressed responses by specifying both Accept-Encoding and User-Agent headers with a value of gzip. The Content-Type of the response is also used to determine whether compression is appropriate; in general, text-based content types are compressed, whereas binary content types are not.

When responses are compressed automatically by App Engine, the Content-Encoding header is added to the response.

Headers removed

The following headers are ignored and removed from the response:

  • Connection
  • Content-Encoding*
  • Date
  • Keep-Alive
  • Proxy-Authenticate
  • Server
  • Trailer
  • Transfer-Encoding
  • Upgrade

* May be re-added if the response is compressed by App Engine.

In addition, the header Strict-Transport-Security is removed from responses served from any domains other than *

Headers with non-ASCII characters in either the name or value are also removed.

Headers added or replaced

An application must not set the Content-Length header in the response.

The following headers can be added or replaced in the response:

Cache-Control, Expires and Vary

These headers specify caching policy to intermediate web proxies, such as Internet Service Providers, and browsers. If your script sets these headers, they will usually be unmodified, unless the response has a Set-Cookie header, or is generated for a user who is signed in using an administrator account.

If you have a Set-Cookie response header, the Cache-Control header is set to private (if it is not already more restrictive) and the Expires header will be set to the current date, if it is not already in the past. Generally, this will allow browsers to cache the response, but not intermediate proxy servers. This is for security reasons, because if the response was cached publicly, another user could subsequently request the same resource, and retrieve the first user's cookie.

Depending upon the request headers and response Content-Type header, the server might automatically compress the response body, as described above. In this case, it adds a Content-Encoding: gzip header to indicate that the body is compressed. For more detail, see the section on response compression.
Content-Length or Transfer-Encoding
The server always ignores the Content-Length header returned by the application. It will either set Content-Length to the length of the body after compression, if compression is applied, or delete Content-Length, and use chunked transfer encoding by adding a Transfer-Encoding: chunked header.

If you do not explicitly set this header, the http.ResponseWriter class detects the content type from the start of the response body, and sets the Content-Type header accordingly.

Set to the current date and time.
Set to Google Frontend.

If you access your site while signed in using an administrator account, App Engine includes per-request statistics in the response headers:

An estimate of what 1,000 requests similar to this request would cost in US dollars.
The resources used by the request, including server-side time as a number of milliseconds.

Responses with resource usage statistics will be made uncacheable.

Quotas and limits

Google App Engine automatically allocates resources to your application as traffic increases. However, this is bound by the following restrictions:

  • App Engine reserves automatic scaling capacity for applications with low latency, where the application responds to requests in less than one second. Applications with very high latency, such as over one second per request for many requests, and high throughput require Silver, Gold, or Platinum support. Customers with this level of support can request higher throughput limits by contacting their support representative.

  • Applications that are heavily CPU-bound may also incur some additional latency in order to efficiently share resources with other applications on the same servers. Requests for static files are exempt from these latency limits.

Each incoming request to the application counts toward the Requests limit. Data sent in response to a request counts toward the Outgoing Bandwidth (billable) limit.

Both HTTP and HTTPS (secure) requests count toward the Requests, Incoming Bandwidth (billable), and Outgoing Bandwidth (billable) limits. The Cloud Platform Console Quota Details page also reports Secure Requests, Secure Incoming Bandwidth, and Secure Outgoing Bandwidth as separate values for informational purposes. Only HTTPS requests count toward these values. For more information, see the Quotas page.

Send feedback about...

App Engine flexible environment for Go