> ## Documentation Index
> Fetch the complete documentation index at: https://the-early-spring18.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Google REST API Overview: Formats, Limits, and Errors

> Introduction to the Google REST API — base URL, versioning, request/response formats, rate limits, pagination, and error handling conventions.

The Google REST API gives you programmatic access to a cloud-based platform built for searching, organizing, and acting on information at scale. Every interaction follows standard REST conventions: you send HTTP requests to well-defined endpoints, and the API responds with structured JSON. Whether you are building a lightweight integration or a production-grade data pipeline, understanding the foundational conventions below — base URL, versioning, request and response formats, rate limits, pagination, and error handling — will help you build confidently and avoid common pitfalls from the start.

## Base URL

All API requests are made to the following base URL:

```
https://api.google.com/v1
```

Every endpoint path you encounter in this documentation is relative to this base URL. For example, the search endpoint is reached at `https://api.google.com/v1/search`. You should store this base URL in a configuration variable in your application so you can update it in one place if needed.

<Info>
  Always use HTTPS when making requests. Plain HTTP requests will be rejected to protect your data and credentials in transit.
</Info>

## Versioning

The current stable version of the API is **v1**, which is reflected directly in the URL path. This explicit versioning strategy ensures that breaking changes to the API never affect your integration without advance notice.

When a new major version is released, the older version enters a deprecation period. During this window, you will receive email notifications at the address associated with your account, along with a deprecation timeline and a migration guide. You can continue using `v1` endpoints until the version is formally retired.

<Note>
  Minor, backwards-compatible changes — such as new optional fields or additional endpoints — may be introduced to the current version at any time without a version bump. Subscribe to the changelog to stay informed.
</Note>

## Request Format

All request bodies must be sent as valid JSON with the `Content-Type` header set to `application/json`. Requests that omit this header or submit malformed JSON will receive a `400 Bad Request` response.

```bash theme={null}
curl https://api.google.com/v1/search \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"q": "example query"}'
```

Query parameters should be URL-encoded when passed in the request URL. For `GET` requests, no request body is required or expected.

## Response Format

Every response from the API is returned as JSON and wrapped in a consistent envelope structure. The `data` field contains the resource or collection you requested, while the `meta` field includes contextual metadata about the request itself — useful for logging, tracing, and debugging.

```json theme={null}
{
  "data": { "..." : "..." },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-06-01T10:00:00Z"
  }
}
```

The `request_id` field within `meta` uniquely identifies each API call. You should log this value alongside your own application logs so you can correlate activity and reference it when contacting support.

## Rate Limits

The API enforces rate limits to ensure fair usage and platform stability across all customers. Limits are applied per API key and vary by subscription plan.

| Plan       | Requests per Minute | Requests per Day |
| ---------- | ------------------- | ---------------- |
| Free       | 60                  | 10,000           |
| Pro        | 300                 | 100,000          |
| Enterprise | Unlimited           | Unlimited        |

When you exceed your rate limit, the API returns a `429 Too Many Requests` response. The response will include a `Retry-After` header indicating the number of seconds you should wait before retrying the request.

<Warning>
  Retrying immediately after a `429` without honoring the `Retry-After` header will continue to result in rejected requests and may temporarily increase your backoff window. Always implement exponential backoff in your retry logic.
</Warning>

## Pagination

Endpoints that return collections of resources support cursor-free, offset-based pagination via two query parameters:

| Parameter | Default | Maximum | Description                    |
| --------- | ------- | ------- | ------------------------------ |
| `page`    | `1`     | —       | The page number to retrieve    |
| `limit`   | `20`    | `100`   | The number of results per page |

Paginated responses include additional fields alongside `data` to help you navigate the full result set:

```json theme={null}
{
  "data": ["..."],
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-06-01T10:00:00Z",
    "total": 243,
    "page": 2,
    "pages": 13
  }
}
```

Use `total` to display result counts in your UI, and `pages` to know when you have reached the last page. If `page` exceeds `pages`, the API returns an empty `data` array rather than an error.

## Error Handling

When a request cannot be completed successfully, the API returns a structured error object instead of a `data` payload. The `code` field provides a machine-readable identifier you can use in your application logic, while `message` provides a human-readable explanation. The `request_id` ties the error back to the specific API call.

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found.",
    "request_id": "req_abc123"
  }
}
```

The table below summarizes the HTTP status codes you may encounter and what each one means in the context of this API:

| Status Code | Name                  | When You'll See It                                              |
| ----------- | --------------------- | --------------------------------------------------------------- |
| `200`       | OK                    | The request succeeded and the response body contains the result |
| `201`       | Created               | A new resource was successfully created                         |
| `400`       | Bad Request           | The request body or parameters are malformed or invalid         |
| `401`       | Unauthorized          | Your API key is missing or invalid                              |
| `403`       | Forbidden             | Your API key lacks the required scope for this operation        |
| `404`       | Not Found             | The specified resource does not exist                           |
| `429`       | Too Many Requests     | You have exceeded your plan's rate limit                        |
| `500`       | Internal Server Error | An unexpected error occurred on the server                      |

<Tip>
  When contacting support about an unexpected API error, always include the value of the `X-Request-Id` response header (or the `request_id` from the response body) in your message. This identifier allows the support team to locate the exact request in server logs and dramatically speeds up diagnosis.
</Tip>