evernote-common-errors

Evernote Common Errors

Overview

Comprehensive guide to diagnosing and resolving Evernote API errors. Evernote uses three exception types: EDAMUserException (client errors), EDAMSystemException (server/rate limit errors), and EDAMNotFoundException (invalid GUIDs).

Prerequisites

• Basic Evernote SDK setup
• Understanding of Evernote data model

Instructions

EDAMUserException Error Codes

Code	Name	Cause	Fix
1	BAD_DATA_FORMAT	Invalid ENML, missing DOCTYPE	Validate ENML before sending; check for forbidden elements
2	DATA_REQUIRED	Missing required field (title, content)	Ensure note.title and note.content are set
3	PERMISSION_DENIED	API key lacks permissions	Request additional permissions from Evernote
4	INVALID_AUTH	Invalid or revoked token	Re-authenticate user via OAuth
5	AUTH_EXPIRED	Token past expiration date	Check edam_expires, refresh token
6	LIMIT_REACHED	Account limit exceeded (250 notebooks)	Clean up resources before creating new ones
7	QUOTA_REACHED	Monthly upload quota exceeded	Check user.accounting.remaining

ENML Validation

The most common error is BAD_DATA_FORMAT from invalid ENML. Validate before sending:

function validateENML(content) {
  const errors = [];
  if (!content.includes('<?xml version="1.0"')) errors.push('Missing XML declaration');
  if (!content.includes('<!DOCTYPE en-note')) errors.push('Missing DOCTYPE');
  if (!content.includes('<en-note>')) errors.push('Missing <en-note> root');

  const forbidden = [/<script/i, /<form/i, /<iframe/i, /<input/i];
  forbidden.forEach(p => { if (p.test(content)) errors.push(`Forbidden: ${p.source}`); });

  if (/\s(class|id|onclick)=/i.test(content)) errors.push('Forbidden attributes');
  return { valid: errors.length === 0, errors };
}

EDAMSystemException Handling

Rate limit errors include rateLimitDuration (seconds to wait). Maintenance errors should be retried with progressive backoff.

async function withRetry(operation, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation();
    } catch (error) {
      if (error.rateLimitDuration) {
        await new Promise(r => setTimeout(r, error.rateLimitDuration * 1000));
        continue;
      }
      throw error;
    }
  }
}

EDAMNotFoundException Handling

Thrown when a GUID does not exist (deleted note, wrong user, invalid format). Handle gracefully by returning null instead of throwing.

async function safeGetNote(noteStore, guid) {
  try {
    return await noteStore.getNote(guid, true, false, false, false);
  } catch (error) {
    if (error.identifier === 'Note.guid') return null;
    throw error;
  }
}

Error Handler Service

Build a centralized error handler that classifies exceptions and returns structured results with type, code, action, and recoverable flags. See Implementation Guide for the complete EvernoteErrorHandler class.

Output

• Error code reference table for all EDAMUserException codes
• ENML validation utility that catches common content errors
• Rate limit retry with rateLimitDuration handling
• Safe getter pattern for EDAMNotFoundException
• Centralized EvernoteErrorHandler service class

Error Handling

Exception	When Thrown	Recovery
EDAMUserException	Client error (invalid input, permissions)	Fix input or re-authenticate
EDAMSystemException	Server error (rate limits, maintenance)	Wait and retry
EDAMNotFoundException	Resource not found (invalid GUID)	Verify GUID, check trash

Resources

• Error Handling
• Rate Limits
• API Reference
• ENML DTD

Next Steps

For debugging tools and techniques, see evernote-debug-bundle.

Examples

ENML debugging: Note creation fails with BAD_DATA_FORMAT. Run validateENML() on the content to identify missing DOCTYPE, unclosed tags, or forbidden elements like <script>.

Token refresh flow: API call returns AUTH_EXPIRED (code 5). Check stored edam_expires timestamp, redirect user to OAuth re-authorization, store new token with updated expiration.