Error Codes¶

All errors follow a consistent JSON structure:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing auth token"
  }
}

Error Codes¶

Code	Meaning	Resolution
`UNAUTHORIZED`	Invalid or missing request token	Check `*_PROXY_TOKEN` env var; rotate with the setup key if the token was lost
`BAD_REQUEST`	Missing required parameter or invalid JSON body	Check parameter names and types against the tool schema
`LIMIT_EXCEEDED`	Request, response, batch, date-window, attachment, export, range, or scan limit exceeded	Reduce page size, date window, range size, batch size, or payload size and retry
`NOT_FOUND`	Resource (file, email, event, spreadsheet, slide, document) not found	Verify the ID is correct and the resource exists
`FORBIDDEN`	Bootstrap already completed	Token is one-time; use the saved token
`RATE_LIMITED`	Exceeded weighted request units for the current minute	Wait 60 seconds; requests reset every minute
`INTERNAL_ERROR`	Unexpected server error	Check Apps Script logs via `clasp logs`; may indicate a code bug
`CREATE_FAILED`	Could not create resource	Usually a permissions issue or invalid input
`UPDATE_FAILED`	Could not update resource	Check you have edit access to the target
`DELETE_FAILED`	Could not delete resource	Check you have delete access or the resource is locked
`MOVE_FAILED`	Could not move resource	Check destination exists and you have access
`FORMAT_FAILED`	Could not apply formatting	Check the range/element exists and accepts formatting
`INSERT_FAILED`	Could not insert element	Check position is valid and element type is supported
`SEND_FAILED`	Email send operation failed	Check recipient addresses and message content
`UNKNOWN_ACTION`	Invalid action name in batch operation	Check action names match the service documentation
`CONFIRMATION_REQUIRED`	Action needs explicit `confirm: true` (send/share/destructive)	Re-run after user approval; CLI uses interactive prompt or `--yes` (never auto-sets without approval)
`ACTION_NOT_ALLOWED`	Token class is not authorized for this action	Use a broader token class or a matching class-scoped token
`BATCH_ACTION_NOT_ALLOWED`	Nested batch op is not on the service batch allowlist	Check `BATCH_ACTIONS` for the service; remove or replace the nested action

Batch Errors¶

In batch operations, errors are collected per-operation. A batch continues executing even if individual operations fail:

{
  "success": true,
  "data": {
    "results": [
      { "index": 0, "action": "fileGet", "success": true, "data": { "..." } },
      { "index": 1, "action": "fileDelete", "success": false, "error": { "code": "NOT_FOUND", "message": "File not found" } },
      { "index": 2, "action": "fileCreate", "success": true, "data": { "..." } }
    ]
  }
}

Check each result's success field to determine if individual operations passed or failed.