Error Codes Reference
Complete reference of GKit SheetsAPI error codes - HTTP status, machine-readable error codes, descriptions, and recommended actions.
Error Codes Reference
All GKit SheetsAPI errors follow a consistent response shape regardless of the HTTP status code.
Error Response Shape
{
"error": {
"code": "INVALID_FILTER",
"message": "The filter expression is malformed or references an unknown column.",
"details": {
"field": "filters[0].column",
"received": "nonexistent_col"
}
}
}code is the machine-readable identifier. message is a human-readable explanation. details is optional and may include field-level context depending on the error type.
400 Bad Request
The request was rejected before reaching the underlying spreadsheet. Fix the request before retrying.
| Error Code | Description | Recommended Action |
|---|---|---|
BAD_REQUEST | The request body or query string is malformed or cannot be parsed. | Validate that the request payload is valid JSON and all required fields are present. |
INVALID_FILTER | A filter expression references an unknown column or uses an unsupported operator. | Check the details.field path and ensure the column name matches one returned by the sheet's schema endpoint. |
INVALID_SORT | The sort parameter specifies an unknown column or an unrecognized direction value. | Use asc or desc and confirm the column exists in the target sheet. |
INVALID_LIMIT | The limit value is not a positive integer, or exceeds the maximum allowed page size. | Use an integer between 1 and 1000. |
MISSING_FIELD | A required field is absent from the request body. | Inspect details.field to identify which field is missing. |
VALIDATION_ERROR | One or more fields failed type or constraint validation (e.g., a string was passed where a number is expected). | Review details for per-field validation messages and correct the values accordingly. |
401 Unauthorized
The request could not be authenticated. The client must supply a valid API key.
| Error Code | Description | Recommended Action |
|---|---|---|
UNAUTHORIZED | No API key was included in the request. | Add an Authorization: Bearer <key> header to every request. |
INVALID_KEY | The API key supplied does not match any active key in the system. | Verify the key value and that it was copied without trailing whitespace. |
EXPIRED_KEY | The API key has passed its expiry date or was manually revoked. | Rotate the key in the GKit dashboard and update all consumers. |
403 Forbidden
The key is valid but lacks the necessary permission or the account has hit a plan boundary.
| Error Code | Description | Recommended Action |
|---|---|---|
FORBIDDEN | The authenticated key does not have the required scope for this operation (e.g., a read-only key attempting a write). | Confirm the key's assigned scopes in the dashboard and use a key with the appropriate permissions. |
SHEET_NOT_SHARED | The target Google Sheet has not been shared with the GKit service account. | Open the sheet in Google Drive, share it with the GKit service account email, and retry. |
PLAN_LIMIT | The operation would exceed a hard limit imposed by the account's current billing plan (e.g., maximum connected sheets). | Upgrade the plan or remove unused sheet connections before retrying. |
404 Not Found
The requested resource does not exist or is not accessible to the authenticated key.
| Error Code | Description | Recommended Action |
|---|---|---|
SHEET_NOT_FOUND | No sheet matching the provided sheet ID is connected to this account. | Confirm the sheet ID is correct and that the sheet has been connected in the GKit dashboard. |
ROW_NOT_FOUND | The row ID supplied in the path does not exist in the target sheet. | Retrieve the current row list to confirm the ID before attempting updates or deletes. |
USER_NOT_FOUND | The user referenced in the request does not exist. | Verify the user identifier and that the account has not been deleted. |
409 Conflict
The request conflicts with the current state of the resource.
| Error Code | Description | Recommended Action |
|---|---|---|
CONFLICT | A write operation cannot be applied because it conflicts with a concurrent modification. | Re-fetch the resource, apply changes on top of the latest version, and retry. |
DUPLICATE_IDEMPOTENCY_KEY | A request with the same Idempotency-Key header was already processed successfully. | If the original request succeeded, no action is needed. If you intend a new operation, supply a fresh idempotency key. |
429 Too Many Requests
The client has exceeded an allowed request rate or usage quota.
| Error Code | Description | Recommended Action |
|---|---|---|
RATE_LIMITED | Too many requests were sent within a short time window. | Honour the Retry-After response header and implement exponential back-off before retrying. |
QUOTA_EXCEEDED | The monthly or daily request quota for the account has been consumed. | Wait for the quota to reset (see X-Quota-Reset header) or upgrade the plan for a higher quota. |
500 / 503 Server Errors
An unexpected condition occurred on the GKit or Google Sheets side.
| HTTP Status | Error Code | Description | Recommended Action |
|---|---|---|---|
500 | INTERNAL_ERROR | An unhandled exception occurred while processing the request. | Retry with exponential back-off. If the error persists, contact support and include the X-Request-Id header value from the response. |
503 | SERVICE_UNAVAILABLE | GKit or an upstream Google service is temporarily unavailable. | Check the GKit status page and retry after the outage is resolved. |
Working with the X-Request-Id Header
Every response includes an X-Request-Id header. Include this value when contacting support - it allows the team to locate the exact request in server-side logs without needing to reproduce the issue.