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