ERPNext API Error Handling

Patterns for handling errors in API development. For syntax details, see

erpnext-api-patterns

.

Version

v14/v15/v16 compatible API Error Handling Overview ┌─────────────────────────────────────────────────────────────────────┐ │ API ERROR HANDLING DECISION │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ Where is the error occurring? │ │ │ │ Server-side (Python)? │ │ ├── Validation error → frappe.throw() with clear message │ │ ├── Permission error → frappe.throw() + PermissionError │ │ ├── Not found → frappe.throw() + DoesNotExistError │ │ └── Unexpected → Log + generic error to client │ │ │ │ Client-side (JavaScript)? │ │ ├── frappe.call → Use error callback or .catch() │ │ └── frappe.xcall → Use try/catch with async/await │ │ │ │ External integration? │ │ └── requests library → try/except with specific exceptions │ │ │ └─────────────────────────────────────────────────────────────────────┘ HTTP Status Codes Reference Code Meaning When Frappe Uses 200 Success Normal response 400 Bad Request Validation error 403 Forbidden Permission denied 404 Not Found Document doesn't exist 417 Expectation Failed frappe.throw() called 500 Server Error Unhandled exception Server-Side Patterns Basic Whitelisted Method @frappe . whitelist ( ) def update_status ( docname , status ) :

Validate input

if not docname : frappe . throw ( _ ( "Document name is required" ) , frappe . ValidationError ) if status not in [ "Draft" , "Submitted" , "Cancelled" ] : frappe . throw ( _ ( "Invalid status: {0}" ) . format ( status ) ) try : doc = frappe . get_doc ( "My DocType" , docname ) doc . status = status doc . save ( ) return { "success" : True , "name" : doc . name } except frappe . DoesNotExistError : frappe . throw ( _ ( "Document {0} not found" ) . format ( docname ) ) except frappe . PermissionError : frappe . throw ( _ ( "Permission denied" ) , frappe . PermissionError ) Bulk Operation with Partial Failure @frappe . whitelist ( ) def bulk_update ( items ) : items = frappe . parse_json ( items ) results = { "success" : [ ] , "failed" : [ ] } for item in items : try : doc = frappe . get_doc ( "Item" , item [ "name" ] ) doc . update ( item ) doc . save ( ) results [ "success" ] . append ( item [ "name" ] ) except Exception as e : results [ "failed" ] . append ( { "name" : item [ "name" ] , "error" : str ( e ) } ) frappe . db . commit ( ) return results Client-Side Patterns frappe.call Error Handling frappe . call ( { method : "myapp.api.update_status" , args : { docname : "DOC-001" , status : "Submitted" } , callback : function ( r ) { if ( r . message && r . message . success ) { frappe . show_alert ( { message : __ ( "Updated" ) , indicator : "green" } ) ; } } , error : function ( r ) { // Called on HTTP error or frappe.throw frappe . msgprint ( { title : __ ( "Error" ) , message : r . message || __ ( "Operation failed" ) , indicator : "red" } ) ; } } ) ; async/await Pattern async function updateDocument ( docname , status ) { try { const result = await frappe . xcall ( "myapp.api.update_status" , { docname : docname , status : status } ) ; return result ; } catch ( error ) { console . error ( "API Error:" , error ) ; frappe . throw ( __ ( "Failed to update document" ) ) ; } } External API Pattern import requests def call_external_api ( endpoint , data ) : try : response = requests . post ( endpoint , json = data , timeout = 30 , headers = { "Authorization" : f"Bearer { get_api_key ( ) } " } ) response . raise_for_status ( ) return response . json ( ) except requests . Timeout : frappe . log_error ( "External API timeout" , "API Integration" ) frappe . throw ( _ ( "External service timeout. Please try again." ) ) except requests . HTTPError as e : frappe . log_error ( f"HTTP { e . response . status_code } " , "API Integration" ) frappe . throw ( _ ( "External service error" ) ) except requests . RequestException as e : frappe . log_error ( str ( e ) , "API Integration" ) frappe . throw ( _ ( "Connection failed" ) ) Critical Rules ✅ ALWAYS Validate input before processing Use frappe.throw() for user-facing errors Log unexpected errors with frappe.log_error() Return structured responses from APIs Handle both success and error in callbacks ❌ NEVER Expose internal error details to users Catch exceptions without logging Return raw exception messages Assume API calls will succeed Skip input validation Quick Reference: Error Responses

User-facing error (shows alert)

frappe . throw ( _ ( "Clear error message" ) )

Permission error (403)

frappe . throw ( _ ( "Not allowed" ) , frappe . PermissionError )

Validation error (400)

frappe . throw ( _ ( "Invalid input" ) , frappe . ValidationError )

Log error (no user message)

frappe . log_error ( frappe . get_traceback ( ) , "Error Title" ) Reference Files File Contents patterns.md Detailed error handling patterns examples.md Complete working examples anti-patterns.md Common mistakes to avoid See Also erpnext-api-patterns - API implementation patterns erpnext-syntax-whitelisted - Whitelisted method syntax erpnext-errors-serverscripts - Server Script error handling