Apple Notes has no formal API rate limits like cloud services do. However, there are practical throughput limits imposed by three systems: the Apple Events IPC bridge (osascript to Notes.app), the iCloud sync daemon (bird/cloudd) that must process each write, and the Notes.app SQLite database that handles concurrent access. Exceeding these practical limits causes timeouts (-1712), sync lag, or data loss when writes outpace iCloud's upload buffer. This guide documents safe operation rates and provides throttling patterns.
| Operation | Safe Rate | Bottleneck | Exceeding Limit |
|---|---|---|---|
| Create note | 1/second | iCloud sync buffer | Sync lag; notes missing on other devices |
| Read note (name/body) | 10/second | Apple Events IPC | -1712 timeout errors |
Search (.whose()) | 2/second | Notes.app indexer | UI freeze; timeout |
| Move note between folders | 1/second | iCloud + local DB | Folder state inconsistency |
| Delete note | 1/second | iCloud delete propagation | Deleted notes reappear |
| Bulk list (all notes) | 1/10 seconds | Memory + IPC | Process killed by macOS |
| Attachment operations | 1/5 seconds | File I/O + sync | Corrupt or missing attachments |
// src/rate-limit/throttle.ts
import { execSync } from "child_process";
interface ThrottleConfig {
minDelayMs: number;
maxRetries: number;
backoffMultiplier: number;
}
const THROTTLE_CONFIGS: Record<string, ThrottleConfig> = {
read: { minDelayMs: 100, maxRetries: 3, backoffMultiplier: 2 },
write: { minDelayMs: 1000, maxRetries: 5, backoffMultiplier: 2 },
delete: { minDelayMs: 1000, maxRetries: 3, backoffMultiplier: 3 },
search: { minDelayMs: 500, maxRetries: 2, backoffMultiplier: 2 },
};
async function throttledExec<T>(
operation: () => T,
type: keyof typeof THROTTLE_CONFIGS = "write"
): Promise<T> {
const config = THROTTLE_CONFIGS[type];
let delay = config.minDelayMs;
for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
try {
const result = operation();
await new Promise(r => setTimeout(r, config.minDelayMs));
return result;
} catch (e: any) {
if (attempt === config.maxRetries) throw e;
console.warn(`Retry ${attempt + 1}/${config.maxRetries} after ${delay}ms: ${e.message}`);
await new Promise(r => setTimeout(r, delay));
delay *= config.backoffMultiplier;
}
}
throw new Error("Unreachable");
}#!/bin/bash
# Batch create notes with throttling
INPUT_FILE="$1" # JSON array of {title, body} objects
DELAY=1 # seconds between creates
jq -c '.[]' "$INPUT_FILE" | while IFS= read -r note; do
title=$(echo "$note" | jq -r '.title')
body=$(echo "$note" | jq -r '.body')
osascript -l JavaScript -e "
const Notes = Application('Notes');
const n = Notes.Note({name: '$title', body: '$body'});
Notes.defaultAccount.folders[0].notes.push(n);
n.name();
" && echo "Created: $title" || echo "FAILED: $title"
sleep "$DELAY"
done# Monitor iCloud sync backlog during batch operations
watch -n 5 'echo "=== Sync Status ===";
brctl status com.apple.Notes 2>/dev/null || echo "brctl unavailable";
echo ""; echo "=== Note Count ===";
osascript -l JavaScript -e "Application(\"Notes\").defaultAccount.notes.length" 2>/dev/null'| Issue | Cause | Solution |
|---|---|---|
| -1712 AppleEvent timeout | Operations sent faster than Notes can process | Increase delay between operations; use throttled queue |
| Notes reappear after deletion | iCloud sync restored note before delete propagated | Wait 5s after delete; verify deletion on another device |
| Duplicate notes created | Retry on timeout re-executed successful create | Track created note IDs; check before retry |
| iCloud sync stops during bulk ops | Sync daemon overwhelmed | Pause operations for 30s; killall bird to restart sync |
| UI becomes unresponsive | Too many Apple Events queued | Reduce concurrency; add delay(2) in JXA scripts |
For performance optimization beyond throttling, see apple-notes-performance-tuning. For monitoring sync health during operations, see apple-notes-observability.