evernote-common-errors

What this skill does

# 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:

```javascript
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.

```javascript
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.

```javascript
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](references/implementation-guide.md) 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](https://dev.evernote.com/doc/articles/error_handling.php)
- [Rate Limits](https://dev.evernote.com/doc/articles/rate_limits.php)
- [API Reference](https://dev.evernote.com/doc/reference/)
- [ENML DTD](http://xml.evernote.com/pub/enml2.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.