frappe-errors-api

name	frappe-errors-api
description	Use when debugging or handling API errors in Frappe/ERPNext v14/v15/v16. Prevents silent failures and wrong HTTP status codes in REST endpoints. Covers 401 Unauthorized (wrong token format, expired OAuth), 403 Forbidden (missing @whitelist, allow_guest needed), 404 Not Found (wrong endpoint URL), 417 Expectation Failed (validation via frappe.throw), 500 Internal Server Error, CORS issues, CSRF token missing/invalid, rate limit exceeded (429), file upload failures, JSON parse errors in request/response, webhook delivery failures, and timeout on long operations. Keywords: API error, 401, 403, 404, 417, 429, 500, CSRF, CORS, REST, whitelist, webhook, rate limit, file upload, authentication token.
license	MIT
compatibility	Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16.
metadata	{"author":"OpenAEC-Foundation","version":"2.0"}

API Error Handling

For API implementation patterns see frappe-core-api. For permission errors see frappe-errors-permissions.

---

HTTP Status Code Map: Error -> Cause -> Fix

Code	Frappe Exception	When It Happens	Fix
200	—	Success	—
401	AuthenticationError	Bad/expired token, wrong format	Check Authorization: token key:secret or Bearer access_token
403	PermissionError	Missing @whitelist, no role, no allow_guest	Add decorator or grant permission
404	DoesNotExistError	Wrong URL, doc not found, typo in endpoint path	Verify /api/resource/:doctype/:name or /api/method/dotted.path
409	DuplicateEntryError	Unique constraint violated	Check existing records before insert
417	ValidationError	frappe.throw() called	Fix validation logic or input data
429	RateLimitExceededError	Too many requests	Respect Retry-After header; throttle requests
500	Exception (unhandled)	Unhandled server error	Check Error Log; wrap in try/except
503	—	Server overloaded / maintenance	Retry with exponential backoff

---

Authentication Errors (401)

Wrong Token Format

Error:  HTTP 401 Unauthorized
Cause:  Using "Bearer api_key:api_secret" instead of "token api_key:api_secret"

Frappe uses TWO authentication formats — NEVER mix them:

Method	Header Format	When to Use
API Key/Secret	Authorization: token api_key:api_secret	Server-to-server, scripts
OAuth Bearer	Authorization: Bearer access_token	OAuth 2.0 flows
Session Cookie	Cookie from /api/method/login	Browser-based apps

# WRONG — Bearer with API key:secret
headers = {"Authorization": f"Bearer {api_key}:{api_secret}"}

# CORRECT — token keyword for API key:secret
headers = {"Authorization": f"token {api_key}:{api_secret}"}

# CORRECT — Bearer for OAuth access tokens only
headers = {"Authorization": f"Bearer {oauth_access_token}"}

Expired OAuth Token

Error:  HTTP 401 after token was working
Cause:  OAuth access_token expired
Fix:    Use refresh_token to get new access_token

def get_fresh_token(settings):
    """ALWAYS implement token refresh for OAuth integrations."""
    if is_token_expired(settings.token_expiry):
        response = requests.post(f"{settings.base_url}/api/method/frappe.integrations.oauth2.get_token", data={
            "grant_type": "refresh_token",
            "refresh_token": settings.get_password("refresh_token"),
            "client_id": settings.client_id,
        })
        if response.status_code == 200:
            data = response.json()
            settings.access_token = data["access_token"]
            settings.token_expiry = frappe.utils.add_to_date(None, seconds=data["expires_in"])
            settings.save(ignore_permissions=True)
        else:
            frappe.throw(_("OAuth token refresh failed"), exc=frappe.AuthenticationError)
    return settings.access_token

---

Forbidden Errors (403)

Missing @frappe.whitelist()

Error:  HTTP 403 on /api/method/myapp.api.my_function
Cause:  Function exists but lacks @frappe.whitelist() decorator
Fix:    Add decorator — without it, NO external call is allowed

# WRONG — Callable internally but returns 403 via REST
def my_function(name):
    return frappe.get_doc("Item", name)

# CORRECT — Exposed to authenticated users
@frappe.whitelist()
def my_function(name):
    return frappe.get_doc("Item", name)

# CORRECT — Exposed to everyone including unauthenticated
@frappe.whitelist(allow_guest=True)
def public_function():
    return {"status": "ok"}

Missing allow_guest for Public Endpoints

Error:  HTTP 403 for unauthenticated requests
Cause:  @frappe.whitelist() without allow_guest=True
Fix:    Add allow_guest=True — but ALWAYS validate inputs

NEVER use allow_guest=True without input validation — these endpoints are exposed to the internet.

---

Not Found Errors (404)

Common URL Mistakes

Wrong URL	Correct URL	Issue
/api/resource/SalesOrder/SO-001	/api/resource/Sales Order/SO-001	Space in DocType name
/api/method/myapp.my_function	/api/method/myapp.api.my_function	Missing module path
/api/resource/sales_order	/api/resource/Sales Order	Wrong case / underscore
/api/v2/document/Item/ITEM-001 [v14]	/api/resource/Item/ITEM-001	v2 API only in v15+

# ALWAYS URL-encode DocType names with spaces
import urllib.parse
url = f"/api/resource/{urllib.parse.quote('Sales Order')}/{name}"

---

Validation Errors (417)

Every frappe.throw() call returns HTTP 417 by default (unless a specific exception class is provided).

# Returns 417 — generic validation error
frappe.throw(_("Amount must be positive"))

# Returns 417 — with explicit ValidationError type
frappe.throw(_("Amount must be positive"), exc=frappe.ValidationError)

# Returns 403 — PermissionError overrides to 403
frappe.throw(_("Access denied"), exc=frappe.PermissionError)

# Returns 404 — DoesNotExistError overrides to 404
frappe.throw(_("Not found"), exc=frappe.DoesNotExistError)

ALWAYS use the specific exception class so clients can handle error types correctly:

# WRONG — all errors look the same to the client
frappe.throw(_("Customer not found"))  # 417, generic

# CORRECT — client can distinguish 404 from validation error
frappe.throw(_("Customer not found"), exc=frappe.DoesNotExistError)  # 404

---

CSRF Token Errors

Error:  HTTP 403 "CSRF token missing or invalid"
Cause:  POST/PUT/DELETE request without X-Frappe-CSRF-Token header

Rules:

• ALWAYS include X-Frappe-CSRF-Token header for session-based (cookie) auth.
• Token-based auth (Authorization: token ...) does NOT require CSRF token.
• OAuth Bearer auth does NOT require CSRF token.
• The CSRF token is available in frappe.csrf_token in JavaScript or embedded as window.CSRF_TOKEN.

// Browser-side: ALWAYS include CSRF for session-based requests
fetch("/api/method/myapp.api.update", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-Frappe-CSRF-Token": frappe.csrf_token
    },
    body: JSON.stringify({data: "value"})
});

---

CORS Errors

Error:  "Access-Control-Allow-Origin" header missing
Cause:  Cross-origin request not configured in site_config.json

// site_config.json — NEVER use "*" in production
{
    "allow_cors": "https://your-frontend.example.com"
}

For multiple origins [v15+]:

{
    "allow_cors": ["https://app1.example.com", "https://app2.example.com"]
}

---

Rate Limit Errors (429)

Error:  HTTP 429 Too Many Requests
Cause:  Exceeded rate limit configured in site_config.json or hooks.py

# hooks.py — rate limiting on whitelisted methods [v14+]
rate_limit = {"myapp.api.heavy_endpoint": {"limit": 10, "seconds": 60}}

ALWAYS handle 429 in external API calls:

def call_with_rate_limit(url, data):
    response = requests.post(url, json=data, timeout=30)
    if response.status_code == 429:
        wait = int(response.headers.get("Retry-After", 60))
        time.sleep(min(wait, 120))  # Cap at 2 minutes
        response = requests.post(url, json=data, timeout=30)
    response.raise_for_status()
    return response.json()

---

File Upload Errors

Error:  HTTP 500 on /api/method/upload_file
Cause:  Wrong content type, file too large, or missing file field

# CORRECT file upload via REST API
import requests

response = requests.post(
    f"{base_url}/api/method/upload_file",
    headers={"Authorization": f"token {api_key}:{api_secret}"},
    files={"file": ("document.pdf", open("document.pdf", "rb"), "application/pdf")},
    data={
        "doctype": "Sales Invoice",
        "docname": "SINV-001",
        "is_private": 1  # 1 = private, 0 = public
    },
    timeout=60  # ALWAYS set timeout for uploads
)

Common upload failures:

• Content-Type must be multipart/form-data (set automatically by files= param)
• NEVER set Content-Type: application/json for file uploads
• Check max_file_size in site_config.json (default 10MB)
• [v15+] allowed_file_extensions restricts file types

---

JSON Parse Errors

Error:  "Failed to decode JSON" or unexpected behavior
Cause:  API arguments sent as JSON string instead of parsed object

@frappe.whitelist()
def update_items(items):
    # ALWAYS handle both string and parsed input
    if isinstance(items, str):
        try:
            items = frappe.parse_json(items)
        except Exception:
            frappe.throw(_("Invalid JSON format"), exc=frappe.ValidationError)

    if not isinstance(items, (list, dict)):
        frappe.throw(_("Expected list or dict"), exc=frappe.ValidationError)

---

Webhook Delivery Failures

Error:  Webhook not firing or returning errors
Cause:  Target URL unreachable, wrong format, or timeout

Debug checklist:

1. Check Error Log for webhook delivery errors
2. Verify target URL is reachable from server
3. Check webhook condition — is it filtering out the event?
4. [v15+] Check Webhook Request Log for delivery status

# Custom webhook with error handling
@frappe.whitelist(allow_guest=True)
def incoming_webhook():
    """Handle incoming webhook with validation."""
    payload = frappe.request.data
    signature = frappe.request.headers.get("X-Webhook-Signature")

    if not verify_signature(payload, signature):
        frappe.local.response["http_status_code"] = 401
        return {"error": "Invalid signature"}

    try:
        data = frappe.parse_json(payload)
    except Exception:
        frappe.local.response["http_status_code"] = 400
        return {"error": "Invalid JSON payload"}

    # ALWAYS return 200 quickly to prevent sender retries
    frappe.enqueue(process_webhook_data, data=data, queue="short")
    return {"status": "accepted"}

---

Timeout on Long Operations

Error:  HTTP 504 Gateway Timeout or connection reset
Cause:  Operation takes longer than proxy/server timeout (typically 60s)

Fix: Use background jobs for long operations:

@frappe.whitelist()
def start_long_operation(filters):
    """NEVER run long operations synchronously in API calls."""
    job_id = frappe.generate_hash(length=10)

    frappe.enqueue(
        "myapp.tasks.run_long_operation",
        queue="long",
        timeout=600,
        job_id=job_id,
        filters=filters
    )

    return {"status": "queued", "job_id": job_id}

@frappe.whitelist()
def check_job_status(job_id):
    """Poll for job completion."""
    from frappe.utils.background_jobs import get_info
    jobs = get_info()
    for job in jobs:
        if job.get("job_id") == job_id:
            return {"status": job.get("status", "unknown")}
    return {"status": "completed"}

---

Server-Side Error Pattern (Standard)

@frappe.whitelist()
def safe_api_endpoint(docname, action):
    """ALWAYS follow: validate -> check permission -> execute -> handle errors."""

    # 1. Validate input
    if not docname:
        frappe.throw(_("Document name required"), exc=frappe.ValidationError)

    # 2. Check existence
    if not frappe.db.exists("My DocType", docname):
        frappe.throw(_("Document not found"), exc=frappe.DoesNotExistError)

    # 3. Check permission
    frappe.has_permission("My DocType", "write", docname, throw=True)

    # 4. Execute with error handling
    try:
        doc = frappe.get_doc("My DocType", docname)
        result = doc.run_method(action)
        return {"status": "success", "data": result}

    except frappe.ValidationError:
        raise  # Let Frappe handle — returns 417
    except frappe.PermissionError:
        raise  # Let Frappe handle — returns 403
    except Exception:
        frappe.log_error(frappe.get_traceback(), f"API Error: {docname}")
        frappe.throw(_("Operation failed. Please try again."))

---

Client-Side Error Handling

// ALWAYS handle errors in frappe.call
frappe.call({
    method: "myapp.api.safe_api_endpoint",
    args: {docname: "DOC-001", action: "approve"},
    freeze: true,
    freeze_message: __("Processing..."),
    callback: function(r) {
        if (r.message && r.message.status === "success") {
            frappe.show_alert({message: __("Done"), indicator: "green"});
        }
    },
    error: function(r) {
        // ALWAYS check exc_type for specific handling
        if (r.exc_type === "PermissionError") {
            frappe.msgprint(__("You lack permission for this action."));
        } else if (r.exc_type === "DoesNotExistError") {
            frappe.msgprint(__("Record not found."));
        } else if (!r.status) {
            frappe.msgprint(());
        }
    }
});

---

Critical Rules

ALWAYS

1. Use specific exception classes in frappe.throw() — enables correct HTTP status codes
2. Set timeout on all external requests — requests.get(url, timeout=30)
3. Validate ALL inputs before processing — whitelisted methods are callable by any logged-in user
4. Log errors before throwing — frappe.log_error() then frappe.throw()
5. Handle error callback in every frappe.call() — silent failures confuse users
6. Use background jobs for operations exceeding 30 seconds
7. Return 200 quickly from incoming webhooks then process asynchronously

NEVER

1. Expose internal errors to users — log traceback, show friendly message
2. Mix token formats — token key:secret vs Bearer oauth_token
3. Retry 4xx errors (except 429) — they indicate client bugs, not transient failures
4. Skip CSRF token for session-based POST requests — results in 403
5. Set Content-Type: application/json for file uploads — must be multipart/form-data
6. Catch exceptions without logging — makes production debugging impossible
7. Hardcode API credentials — use settings.get_password("field") from a DocType

---

Reference Files

File	Contents
references/patterns.md	Complete whitelisted method, webhook, external API patterns
references/examples.md	Full working API module, client integration, external API client
references/anti-patterns.md	15 common API error handling mistakes

---

See Also

• frappe-core-api — API implementation patterns
• frappe-errors-permissions — Permission error handling (403 deep dive)
• frappe-syntax-whitelisted — Whitelisted method syntax
• frappe-errors-serverscripts — Server Script error handling