API limits and errors
These ceilings protect the shared service. Your dashboard shows request volume and any observed limit events.
By Zainul Ariffin
Requests
120 / minute
Per API key
Response size
4.5 MB
Maximum JSON response
Row threshold
20,000
Observed or enforced per response
Enforcement can be staged
Rate, response-size, and row ceilings can run in observation mode. In that mode, SheetsDB measures an exceedance without rejecting an otherwise valid request. Once enforcement is enabled, these ceilings return
429 or 413. A 4.5 MB platform safety ceiling and a separate hard row safety ceiling apply even in observation mode.Rate-limit headers
Every authenticated request includes the current window information.
| Header | Meaning |
|---|---|
RateLimit-Limit | Maximum requests in the current window. |
RateLimit-Remaining | Requests remaining in the current window. |
RateLimit-Reset | Unix timestamp, in seconds, when the allowance resets. |
Retry-After | Returned with an enforced 429 response. |
X-Request-ID | Opaque support identifier for tracing one request. |
Error reference
Use the stable error code in application logic and the message for debugging.
| Status | Code | Description |
|---|---|---|
401 | UNAUTHORIZED | The bearer API key is missing, invalid, or no longer active. |
400 | INVALID_REQUEST | The request body or sheet reference is invalid. |
400 | SHEET_UNAVAILABLE | The sheet is private, unpublished, missing, or unavailable. |
413 | RESPONSE_TOO_LARGE | The upstream or serialized JSON response is larger than 4.5 MB. |
413 | ROW_LIMIT_EXCEEDED | The parsed Sheet exceeded an enforced or hard row limit. |
429 | RATE_LIMITED | The API key exceeded its enforced per-minute allowance. |
502 | GOOGLE_REQUEST_FAILED | Google could not return a usable sheet response. |
504 | GOOGLE_REQUEST_TIMEOUT | The upstream Google request exceeded the timeout. |
Usage diagnostics and retention
SheetsDB records bounded operational diagnostics for dashboards and troubleshooting. Request telemetry does not store Sheet contents, response bodies, or raw bearer API keys. Sensitive request metadata is encrypted and expires automatically. See the privacy and retention guide.