When you are querying the Developer Knowledge API or Developer Knowledge MCP server in production applications
and AI agents there must be error handling and quota management to attain high
performance.

In this guide, you will learn how to:

- Implement truncated exponential backoff with jitter for HTTP 429 responses.
- Handle canonical gRPC error codes (`INVALID_ARGUMENT`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`).
- Manage MCP connection timeouts and retry logic.
- Apply quota management and caching best practices.

## HTTP 429 rate limiting and exponential backoff

When request rates exceed the default API quota, the service returns an
`HTTP 429 Too Many Requests` error. Applications must implement retry logic
using truncated exponential backoff with jitter to avoid overloading the
service.

### Truncated exponential backoff

Calculate retry delays using the following formula:

`retry_delay = min(max_delay, initial_delay * (2 ^ attempt) + jitter)`

Use the following parameters to calculate retry delays:

- `initial_delay`: initial retry delay (for example, 1.0 second).
- `max_delay`: maximum backoff cap (for example, 32.0 seconds).
- `attempt`: current retry count (0, 1, 2, ...).
- `jitter`: random value between 0 and 1.0 second to prevent thread synchronization spikes (thundering herd problem).

## gRPC error handling

Applications accessing the service over gRPC must inspect canonical
`grpc.StatusCode` values.

### Standard gRPC status codes

The following table lists canonical gRPC status codes returned by the service
and recommended client handling:

| gRPC status code | HTTP status | Root cause | Recommended action |
|---|---|---|---|
| `INVALID_ARGUMENT` | `400 Bad Request` | Malformed query string, invalid parameter format, or invalid field mask. | **Do not retry**. Correct request parameters before repeating. |
| `UNAUTHENTICATED` | `401 Unauthorized` | Missing, expired, or malformed API key or OAuth Bearer token. | **Do not retry**. Refresh credentials or generate a valid API key. |
| `PERMISSION_DENIED` | `403 Forbidden` | API key lacks permission or Developer Knowledge API is disabled in project. | **Do not retry**. Verify API enablement in Google Cloud console. |
| `NOT_FOUND` | `404 Not Found` | Specified `parent` document path does not exist. `BatchGetDocuments` fails atomically if any requested document is not found. | **Do not retry**. Verify document resource name. |
| `RESOURCE_EXHAUSTED` | `429 Too Many Requests` | Rate limit or project quota limit exceeded. | **Retry** using exponential backoff with jitter. |
| `UNAVAILABLE` | `503 Service Unavailable` | Transient network disconnect or server restart. | **Retry** with exponential backoff. |
| `DEADLINE_EXCEEDED` | `504 Gateway Timeout` | Request exceeded configured RPC deadline before completion. | **Retry** with increased client RPC timeout. |

## MCP connection timeout and error management

The Developer Knowledge MCP server is a remote service hosted at
`https://developerknowledge.googleapis.com/mcp` accessed over HTTPS (using HTTP
POST or Server-Sent Events). AI hosts and agents must manage connection
timeouts and tool errors gracefully.

### Tool execution timeouts

When an agent invokes `search_documents`, `get_documents`, or `answer_query`,
tool calls may exceed timeout windows (for example, 30 seconds) if network
connections lag.

To handle tool execution timeouts:

- **Configure client timeouts**: set tool execution timeouts to 30--60 seconds in your MCP host client configuration.
- **Handle network interruptions**: retry failed HTTP requests with exponential backoff when experiencing transient network drops or HTTP 503 responses.
- **Inspect error messages**: parse standard JSON-RPC error messages or HTTP error status codes to distinguish invalid arguments from quota exhaustion.

## Quota management best practices

Follow these best practices to maintain optimal API usage and avoid unexpected
rate limits:

1. **Cache retrieved document content**: store fetched Markdown documents locally or in a cache (such as Redis) when building applications that access the same pages frequently.
2. **Use batch retrieval** : use `documents.batchGet` rather than executing multiple sequential `documents.get` requests.
3. **Optimize query fields** : request only required response fields using selective [field masks](https://google.aip.dev/157#field-masks-parameter) (`fields=results(parent,content)`).
4. **Monitor quota consumption** : track API request rates in the [Google Cloud console API dashboard](https://console.cloud.google.com/apis/dashboard).

## Related content

- [Developer Knowledge quota and limits](https://developers.google.com/knowledge/quota.md.txt)
- [Developer Knowledge API quickstart](https://developers.google.com/knowledge/quickstart.md.txt)
- [Search and retrieve documents](https://developers.google.com/knowledge/search-retrieve.md.txt)
- [Connect to the Developer Knowledge MCP server](https://developers.google.com/knowledge/mcp.md.txt)