OneNote Production Checklist

Overview

OneNote integrations that work perfectly in development break in production in predictable ways: SharePoint document libraries exceed the 5,000-item view threshold and stop returning notebooks, image uploads silently truncate above 4MB, rate limits compound across users during business hours, and MSAL token caches lose state across container restarts. This skill is a comprehensive go/no-go checklist organized by failure category. Each item references the specific Graph API behavior that causes the production failure and provides the fix. Use this checklist during launch reviews — every unchecked item is a production incident waiting to happen.

Prerequisites

• A functional OneNote integration that works in development/staging
• Azure AD app registration with delegated permissions configured
• Access to production monitoring infrastructure (logging, alerting)
• Familiarity with your deployment environment (containers, VMs, serverless)
• Completed

  onenote-security-basics

  and

  onenote-rate-limits

  skills

Instructions

1. Authentication Checklist

acquire_token_silent

tid

Verification test:

import os, time

def verify_auth_resilience(client):
    """Test that auth survives token expiry cycle."""
    # 1. Make a call to confirm auth works
    response = client.me.onenote.notebooks.get()
    assert response.value is not None, "Initial auth failed"

    # 2. Verify token cache exists on disk
    cache_path = os.path.expanduser("~/.onenote-token-cache.json")
    assert os.path.exists(cache_path), "Token cache not persisted"
    stat = os.stat(cache_path)
    assert oct(stat.st_mode)[-3:] == "600", f"Cache permissions {oct(stat.st_mode)} not 600"

    # 3. Verify silent renewal works (simulate expired access token)
    response2 = client.me.onenote.notebooks.get()
    assert response2.value is not None, "Silent renewal failed"
    print("Auth resilience: PASS")

2. Rate Limit Checklist

Retry-After implementation:

async function callWithRetry(
  client: any,
  apiPath: string,
  maxRetries: number = 3
): Promise<any> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await client.api(apiPath).get();
    } catch (error: any) {
      if (error.statusCode === 429 && attempt < maxRetries) {
        const retryAfter = parseInt(error.headers?.["retry-after"] || "5", 10);
        console.warn(
          `Rate limited. Retry-After: ${retryAfter}s (attempt ${attempt + 1}/${maxRetries})`
        );
        await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
      } else {
        throw error;
      }
    }
  }
}

3. Error Handling Checklist

All seven Graph API error codes must have explicit handlers:

400 Bad Request

403 Forbidden

404 Not Found

429 Too Many Requests

500 Internal Server Error

request-id

502 Bad Gateway

507 Insufficient Storage

Critical: Always log the

request-id

import logging

logger = logging.getLogger("onenote")

async def safe_api_call(client, api_path: str):
    try:
        return await client.api(api_path).get()
    except Exception as e:
        request_id = getattr(e, "headers", {}).get("request-id", "unknown")
        logger.error(
            f"Graph API error: {e} | path={api_path} | request-id={request_id}"
        )
        raise

4. Content Validation Checklist

XHTML validation before send:

from html.parser import HTMLParser

SELF_CLOSING_TAGS = {"br", "hr", "img", "input", "meta", "link"}

class XHTMLValidator(HTMLParser):
    def __init__(self):
        super().__init__()
        self.errors = []
        self.open_tags = []

    def handle_starttag(self, tag, attrs):
        if tag not in SELF_CLOSING_TAGS:
            self.open_tags.append(tag)

    def handle_endtag(self, tag):
        if tag in SELF_CLOSING_TAGS:
            return
        if not self.open_tags or self.open_tags[-1] != tag:
            self.errors.append(f"Mismatched close tag: </{tag}>")
        else:
            self.open_tags.pop()

    def validate(self, html: str) -> list[str]:
        self.feed(html)
        if self.open_tags:
            self.errors.append(f"Unclosed tags: {self.open_tags}")
        return self.errors

def validate_page_content(html_body: str) -> tuple[bool, list[str]]:
    """Validate content before sending to OneNote API."""
    issues = []

    # Size check
    size_bytes = len(html_body.encode("utf-8"))
    if size_bytes > 4 * 1024 * 1024:
        issues.append(f"Content too large: {size_bytes / 1024 / 1024:.1f}MB (max 4MB)")

    # XHTML validation
    validator = XHTMLValidator()
    html_errors = validator.validate(html_body)
    issues.extend(html_errors)

    return len(issues) == 0, issues

5. SharePoint-Specific Checklist

GET /sites/{hostname}:/{path}

6. Monitoring Checklist

7. Health Check Endpoint

interface HealthStatus {
  status: "healthy" | "degraded" | "unhealthy";
  checks: Record<string, { ok: boolean; message: string; latencyMs: number }>;
}

async function healthCheck(client: any): Promise<HealthStatus> {
  const checks: HealthStatus["checks"] = {};

  // Auth check: can we get a token?
  const authStart = Date.now();
  try {
    await client.api("/me").select("id").get();
    checks.auth = { ok: true, message: "Token valid", latencyMs: Date.now() - authStart };
  } catch (e: any) {
    checks.auth = { ok: false, message: e.message, latencyMs: Date.now() - authStart };
  }

  // OneNote check: can we reach the API?
  const noteStart = Date.now();
  try {
    await client.api("/me/onenote/notebooks").select("id").top(1).get();
    checks.onenote = { ok: true, message: "API reachable", latencyMs: Date.now() - noteStart };
  } catch (e: any) {
    checks.onenote = { ok: false, message: e.message, latencyMs: Date.now() - noteStart };
  }

  const allOk = Object.values(checks).every((c) => c.ok);
  const anyOk = Object.values(checks).some((c) => c.ok);

  return {
    status: allOk ? "healthy" : anyOk ? "degraded" : "unhealthy",
    checks,
  };
}

8. Go/No-Go Decision Matrix

Launch rule: All "Must-Have" items checked. "Should-Have" items documented as post-launch tasks with owners and deadlines.

Output

After applying this checklist, you will have: verified authentication resilience across token expiry cycles, confirmed rate limit handling with Retry-After parsing, validated all seven error code handlers, ensured XHTML content passes pre-send validation, configured monitoring dashboards with alert thresholds, and documented a clear go/no-go decision with any deferred items tracked.

Error Handling

507 Insufficient Storage

$filter

$top

$skip

Examples

Quick pre-launch validation script:

#!/bin/bash
# Run this before every production deployment
set -e

echo "=== OneNote Production Readiness Check ==="

# 1. Verify auth works
echo -n "Auth check... "
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $TOKEN" \
  "https://graph.microsoft.com/v1.0/me/onenote/notebooks?\$top=1")
[ "$STATUS" = "200" ] && echo "PASS" || echo "FAIL (HTTP $STATUS)"

# 2. Verify token cache exists
echo -n "Token cache... "
[ -f ~/.onenote-token-cache.json ] && echo "PASS" || echo "FAIL (no cache file)"

# 3. Check cache permissions
echo -n "Cache permissions... "
PERMS=$(stat -c %a ~/.onenote-token-cache.json 2>/dev/null || echo "missing")
[ "$PERMS" = "600" ] && echo "PASS" || echo "FAIL ($PERMS, should be 600)"

# 4. Verify .env not in git
echo -n ".env excluded... "
git check-ignore .env > /dev/null 2>&1 && echo "PASS" || echo "FAIL (.env trackable by git)"

echo "=== Complete ==="

Load test estimation (read-only, safe):

import time

def estimate_production_load(client, user_count: int):
    """Measure real API latency to estimate production capacity."""
    latencies = []
    for _ in range(10):
        start = time.time()
        client.me.onenote.notebooks.get()
        latencies.append((time.time() - start) * 1000)

    avg_ms = sum(latencies) / len(latencies)
    p95_ms = sorted(latencies)[int(len(latencies) * 0.95)]

    calls_per_user_per_min = 10  # From cost tuning model
    total_calls_per_min = calls_per_user_per_min * user_count
    tenant_budget_per_min = 1000  # 10,000/10min

    print(f"Avg latency: {avg_ms:.0f}ms | P95: {p95_ms:.0f}ms")
    print(f"Est. {total_calls_per_min} calls/min for {user_count} users")
    print(f"Tenant budget: {tenant_budget_per_min}/min")
    print(f"Utilization: {total_calls_per_min/tenant_budget_per_min*100:.0f}%")
    if total_calls_per_min > tenant_budget_per_min * 0.8:
        print("WARNING: > 80% budget utilization. Apply cost tuning strategies.")

Resources

• OneNote API Overview
• Error Codes
• Best Practices
• Input/Output HTML
• Images & Files
• Known Issues
• Graph Explorer

Next Steps

• Apply

  onenote-security-basics

  if any authentication items failed
• Use

  onenote-cost-tuning

  to optimize before scaling to more users
• See

  onenote-rate-limits

  for advanced queue-based throttling patterns
• Review

  onenote-common-errors

  for error code handling patterns