Understanding Google Cloud API Gateway Quotas and Multi-Backend Routing

Google Cloud API Gateway lets you put a single managed domain in front of multiple serverless backends like Cloud Run and Cloud Functions. It validates API keys, routes incoming URLs, and rejects traffic that exceeds your configured quotas before those requests hit your application code and run up your compute bill.

This guide walks through multi-backend routing and rate limiting with concrete OpenAPI 2.0 and OpenAPI 3.0 specifications, along with the operational quirks you need to know before deploying them to production.

1. Multi-backend routing

A common setup is splitting traffic by URL path, sending /users to a containerized Cloud Run service while routing /orders to a Cloud Function.

API Gateway handles this through backend extensions. In OpenAPI 3.x, you define backends globally and reference them by name in your paths. In OpenAPI 2.0, you specify backend URLs directly on each operation.

1
openapi: 3.0.3
2
info:
3
  title: Multi-Backend API Gateway
4
  description: Routing traffic to multiple serverless backends using OpenAPI 3.x
5
  version: 1.0.0
6

7
# 1. Define the API Gateway endpoint properties
8
servers:
9
  - url: https://example.com
10
    x-google-endpoint: {}
11

12
# 2. Define reusable backend references globally
13
x-google-api-management:
14
  backends:
15
    users-service:
16
      address: https://users-service-xyz.a.run.app
17
      # Optional: set jwtAudience when using deterministic URLs for revisions
18
      jwtAudience: https://users-service-xyz.a.run.app
19
    orders-service:
20
      address: https://us-central1-myproject.cloudfunctions.net/orders
21

22
paths:
23
  # 3. Route specific paths to their designated backend
24
  /users:
25
    get:
26
      summary: Get all users from Cloud Run
27
      operationId: getUsers
28
      x-google-backend:
29
        backend: users-service
30
      responses:
31
        '200':
32
          description: Success
33

34
  /orders:
35
    post:
36
      summary: Create an order via Cloud Function
37
      operationId: createOrder
38
      x-google-backend:
39
        backend: orders-service
40
      responses:
41
        '200':
42
          description: Success

1
swagger: '2.0'
2
info:
3
  title: Multi-Backend API Gateway
4
  description: Routing traffic to multiple serverless backends using OpenAPI 2.0
5
  version: 1.0.0
6
schemes:
7
  - https
8
produces:
9
  - application/json
10

11
paths:
12
  /users:
13
    get:
14
      summary: Get all users from Cloud Run
15
      operationId: getUsers
16
      x-google-backend:
17
        address: https://users-service-xyz.a.run.app
18
        jwt_audience: https://users-service-xyz.a.run.app
19
      responses:
20
        '200':
21
          description: Success
22

23
  /orders:
24
    post:
25
      summary: Create an order via Cloud Function
26
      operationId: createOrder
27
      x-google-backend:
28
        address: https://us-central1-myproject.cloudfunctions.net/orders
29
      responses:
30
        '200':
31
          description: Success

Key rules for OpenAPI 3.x on GCP

Global backend definitions. You must declare your reusable backends in x-google-api-management.backends at the document root.
Path mapping. Use x-google-backend inside path operations and set backend: to the target name defined in your global block.
Single endpoint server. OpenAPI 3.x supports multiple servers, but GCP API Gateway only reads the single server containing the x-google-endpoint: {} extension.
Trailing slashes. API Gateway treats /users and /users/ as distinct paths without automatic redirection. Always map the non-trailing slash version unless you explicitly configure both.

2. Enforcing quotas and rate limits

API Gateway enforces quotas per consumer project rather than per IP address. Setting this up takes three steps.

Step 1. Require API keys for consumer identification

Because quotas track usage per Google Cloud consumer project, requests must supply an API key. API Gateway maps the key back to the caller project to calculate remaining quota.

1
openapi: 3.0.3
2
info:
3
  title: Quota Enforced API
4
  version: 1.0.0
5

6
# 1. Define the security scheme for API keys
7
components:
8
  securitySchemes:
9
    api_key:
10
      type: apiKey
11
      name: key
12
      in: query
13

14
# Apply security globally or on specific methods
15
security:
16
  - api_key: []

1
swagger: '2.0'
2
info:
3
  title: Quota Enforced API
4
  version: 1.0.0
5

6
# 1. Define the security definition for API keys
7
securityDefinitions:
8
  api_key:
9
    type: apiKey
10
    name: key
11
    in: query
12

13
# Apply security globally or on specific methods
14
security:
15
  - api_key: []

Step 2. Define metrics and quota limits

Define the named metric and its rate allowance. In OpenAPI 3.x, use x-google-api-management at the document root. In OpenAPI 2.0, use x-google-management.

1
# 2. Define the metric and the limit in OpenAPI 3.0
2
x-google-api-management:
3
  metrics:
4
    - name: "read-requests"
5
      displayName: "Read Requests Metric"
6
  quotas:
7
    limits:
8
      - name: "read-limit-per-minute"
9
        metric: "read-requests"
10
        allowance: 100
11
        period: "1m"  # Allowed values: 1m (per minute) or 1d (per day)

1
# 2. Define the metric and the limit in OpenAPI 2.0
2
x-google-management:
3
  metrics:
4
    - name: "read-requests"
5
      displayName: "Read Requests Metric"
6
      valueType: INT64
7
      metricKind: DELTA
8
  quota:
9
    limits:
10
      - name: "read-limit-per-minute"
11
        metric: "read-requests"
12
        unit: "1/min/{project}"
13
        values:
14
          STANDARD: 100

Step 3. Attach the quota to an API operation

Bind individual operations to your metric with x-google-quota and declare how many units each call costs.

1
paths:
2
  /items:
3
    get:
4
      summary: List items
5
      operationId: listItems
6
      # 3. Deduct 1 unit from read-requests per call
7
      x-google-quota:
8
        metricCosts:
9
          "read-requests": 1
10
      responses:
11
        '200':
12
          description: Success

1
paths:
2
  /items:
3
    get:
4
      summary: List items
5
      operationId: listItems
6
      # 3. Deduct 1 unit from read-requests per call
7
      x-google-quota:
8
        metricCosts:
9
          "read-requests": 1
10
      responses:
11
        '200':
12
          description: Success

3. Complete production example

Here is a full inventory service configuration combining backends, API key authentication, and rate limiting in a single file.

1
openapi: 3.0.3
2
info:
3
  title: Secure Inventory API
4
  description: API Gateway configuration with Cloud Run backend and per-minute quotas
5
  version: 1.0.0
6

7
servers:
8
  - url: https://example.com
9
    x-google-endpoint: {}
10

11
x-google-api-management:
12
  backends:
13
    inventory-backend:
14
      address: https://inventory-service-xyz.a.run.app
15
  metrics:
16
    - name: "inventory-reads"
17
      displayName: "Inventory Read Actions"
18
  quotas:
19
    limits:
20
      - name: "per-minute-limit"
21
        metric: "inventory-reads"
22
        allowance: 60
23
        period: "1m"
24

25
components:
26
  securitySchemes:
27
    api_key:
28
      type: apiKey
29
      name: key
30
      in: query
31

32
paths:
33
  /v1/products:
34
    get:
35
      summary: Retrieve all products
36
      operationId: getProducts
37
      security:
38
        - api_key: []
39
      x-google-quota:
40
        metricCosts:
41
          "inventory-reads": 1
42
      x-google-backend:
43
        backend: inventory-backend
44
      responses:
45
        '200':
46
          description: OK
47
          content:
48
            application/json:
49
              schema:
50
                type: array
51
                items:
52
                  type: object
53
                  properties:
54
                    id:
55
                      type: string
56
                    name:
57
                      type: string

1
swagger: '2.0'
2
info:
3
  title: Secure Inventory API
4
  description: API Gateway configuration with Cloud Run backend and per-minute quotas
5
  version: 1.0.0
6
schemes:
7
  - https
8
produces:
9
  - application/json
10

11
x-google-management:
12
  metrics:
13
    - name: "inventory-reads"
14
      displayName: "Inventory Read Actions"
15
      valueType: INT64
16
      metricKind: DELTA
17
  quota:
18
    limits:
19
      - name: "per-minute-limit"
20
        metric: "inventory-reads"
21
        unit: "1/min/{project}"
22
        values:
23
          STANDARD: 60
24

25
securityDefinitions:
26
  api_key:
27
    type: apiKey
28
    name: key
29
    in: query
30

31
paths:
32
  /v1/products:
33
    get:
34
      summary: Retrieve all products
35
      operationId: getProducts
36
      security:
37
        - api_key: []
38
      x-google-quota:
39
        metricCosts:
40
          "inventory-reads": 1
41
      x-google-backend:
42
        address: https://inventory-service-xyz.a.run.app
43
      responses:
44
        '200':
45
          description: OK
46
          schema:
47
            type: array
48
            items:
49
              type: object
50
              properties:
51
                id:
52
                  type: string
53
                name:
54
                  type: string

4. Operational behavior and quirks

Before relying on API Gateway quotas in production, keep these operational details in mind.

HTTP 429 on quota exhaustion

When a consumer runs out of quota, API Gateway cuts off the request upstream before forwarding it to Cloud Run or Cloud Functions:

1
HTTP/1.1 429 Too Many Requests
2
Content-Type: application/json
3

4
{
5
  "code": 429,
6
  "message": "Resource has been exhausted (e.g. check quota)."
7
}

This prevents wasted compute, cold starts, and backend congestion from abusive callers.

Fail-closed behavior

For 4xx client-side quota and key validation errors, API Gateway fails closed. If an API key is missing or invalid, or if the calling project has exceeded its quota, the gateway drops the request immediately.

Proxy batching and the 30% accuracy margin

API Gateway checks quotas in local proxy memory to keep latency down. It does not make a synchronous network round-trip to a central counter on every incoming request.

Under sharp traffic bursts, expect an approximate 30% margin of error. A limit set to 100 requests per minute might allow 120 or 130 requests through before the proxies sync and start returning 429s. If you need hard, single-digit transaction limits, enforce them in your application layer with Redis or Cloud Spanner locks.

Safe metric updates

Note

Do not rename or delete active metrics in a live API configuration. If an incoming request targets a metric name missing from the current active gateway deployment, API Gateway throws an error immediately. Deploy a new API config alongside the existing one and verify traffic before switching over.