Error handling, rate limiting, and quota management

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 (fields=results(parent,content)).
  4. Monitor quota consumption: track API request rates in the Google Cloud console API dashboard.

Related content