@jwikman/bc-code-intelligence-mcp 1.5.7-dev.1

package/embedded-knowledge/domains/jordan-bridge/samples/api-error-responses.md

@@ -0,0 +1,479 @@
+# Business Central API Error Response Patterns - AL Code Sample
+
+## Basic API Error Handling
+
+```al
+page 50120 "Customer API Error Handling"
+{
+    PageType = API;
+    APIPublisher = 'contoso';
+    APIGroup = 'customers';
+    APIVersion = 'v1.0';
+    EntityName = 'customer';
+    EntitySetName = 'customers';
+    SourceTable = Customer;
+    DelayedInsert = true;
+    
+    layout
+    {
+        area(Content)
+        {
+            repeater(Records)
+            {
+                field(id; Rec.SystemId)
+                {
+                    Caption = 'Id';
+                }
+                
+                field(number; Rec."No.")
+                {
+                    Caption = 'Number';
+                    trigger OnValidate()
+                    begin
+                        // Validation error - returns 400 Bad Request
+                        if Rec."No." = '' then
+                            Error('Customer number cannot be empty');
+                            
+                        if StrLen(Rec."No.") > 20 then
+                            Error('Customer number cannot exceed 20 characters');
+                            
+                        // Check for duplicates - returns 400 Bad Request
+                        if CustomerExists(Rec."No.") then
+                            Error('Customer with number %1 already exists', Rec."No.");
+                    end;
+                }
+                
+                field(name; Rec.Name)
+                {
+                    Caption = 'Name';
+                    trigger OnValidate()
+                    begin
+                        // Required field validation
+                        if Rec.Name = '' then
+                            Error('Customer name is required');
+                    end;
+                }
+                
+                field(creditLimit; Rec."Credit Limit (LCY)")
+                {
+                    Caption = 'Credit Limit';
+                    trigger OnValidate()
+                    begin
+                        // Business logic validation
+                        if Rec."Credit Limit (LCY)" < 0 then
+                            Error('Credit limit cannot be negative');
+                            
+                        // Custom business rule
+                        if (Rec."Credit Limit (LCY)" > 100000) and (Rec."Customer Posting Group" <> 'WHOLESALE') then
+                            Error('Credit limit above 100,000 requires wholesale customer posting group');
+                    end;
+                }
+                
+                field(blocked; Rec.Blocked)
+                {
+                    Caption = 'Blocked';
+                }
+            }
+        }
+    }
+    
+    // Custom validation procedures
+    local procedure CustomerExists(CustomerNo: Code[20]): Boolean
+    var
+        Customer: Record Customer;
+    begin
+        Customer.SetRange("No.", CustomerNo);
+        exit(not Customer.IsEmpty);
+    end;
+}
+```
+
+## Advanced Error Handling with Custom Messages
+
+```al
+codeunit 50120 "API Error Management"
+{
+    // Helper procedures for consistent API error handling
+    
+    procedure ValidateCustomerForAPI(var Customer: Record Customer)
+    begin
+        // Comprehensive customer validation
+        ValidateRequiredFields(Customer);
+        ValidateBusinessRules(Customer);
+        ValidateDataIntegrity(Customer);
+    end;
+    
+    local procedure ValidateRequiredFields(var Customer: Record Customer)
+    begin
+        if Customer."No." = '' then
+            ThrowValidationError('MISSING_CUSTOMER_NUMBER', 'Customer number is required');
+            
+        if Customer.Name = '' then
+            ThrowValidationError('MISSING_CUSTOMER_NAME', 'Customer name is required');
+            
+        if Customer."Customer Posting Group" = '' then
+            ThrowValidationError('MISSING_POSTING_GROUP', 'Customer posting group is required');
+    end;
+    
+    local procedure ValidateBusinessRules(var Customer: Record Customer)
+    var
+        CustomerPostingGroup: Record "Customer Posting Group";
+        PaymentTerms: Record "Payment Terms";
+    begin
+        // Validate posting group exists
+        if not CustomerPostingGroup.Get(Customer."Customer Posting Group") then
+            ThrowValidationError('INVALID_POSTING_GROUP', 
+                StrSubstNo('Customer posting group %1 does not exist', Customer."Customer Posting Group"));
+                
+        // Validate payment terms if specified
+        if Customer."Payment Terms Code" <> '' then
+            if not PaymentTerms.Get(Customer."Payment Terms Code") then
+                ThrowValidationError('INVALID_PAYMENT_TERMS',
+                    StrSubstNo('Payment terms %1 do not exist', Customer."Payment Terms Code"));
+                    
+        // Credit limit business rules
+        if Customer."Credit Limit (LCY)" > 1000000 then
+            ThrowValidationError('CREDIT_LIMIT_EXCEEDED',
+                'Credit limit cannot exceed 1,000,000 without special approval');
+    end;
+    
+    local procedure ValidateDataIntegrity(var Customer: Record Customer)
+    var
+        ExistingCustomer: Record Customer;
+    begin
+        // Check for duplicate customer names in same posting group
+        ExistingCustomer.SetRange("Customer Posting Group", Customer."Customer Posting Group");
+        ExistingCustomer.SetRange(Name, Customer.Name);
+        ExistingCustomer.SetFilter("No.", '<>%1', Customer."No.");
+        
+        if not ExistingCustomer.IsEmpty then
+            ThrowValidationError('DUPLICATE_CUSTOMER_NAME',
+                StrSubstNo('Customer with name %1 already exists in posting group %2', 
+                    Customer.Name, Customer."Customer Posting Group"));
+    end;
+    
+    local procedure ThrowValidationError(ErrorCode: Text; ErrorMessage: Text)
+    begin
+        // This creates a structured error response
+        // BC automatically wraps this in proper OData error format
+        Error('API_VALIDATION_ERROR:%1:%2', ErrorCode, ErrorMessage);
+    end;
+}
+
+// Usage in API page
+page 50121 "Customer API Enhanced"
+{
+    PageType = API;
+    APIPublisher = 'contoso';
+    APIGroup = 'customers';
+    APIVersion = 'v2.0';
+    EntityName = 'customer';
+    EntitySetName = 'customers';
+    SourceTable = Customer;
+    DelayedInsert = true;
+    
+    layout
+    {
+        area(Content)
+        {
+            repeater(Records)
+            {
+                field(id; Rec.SystemId)
+                {
+                    Caption = 'Id';
+                }
+                
+                field(number; Rec."No.")
+                {
+                    Caption = 'Number';
+                }
+                
+                field(name; Rec.Name)
+                {
+                    Caption = 'Name';
+                }
+                
+                field(customerPostingGroup; Rec."Customer Posting Group")
+                {
+                    Caption = 'Customer Posting Group';
+                }
+                
+                field(creditLimit; Rec."Credit Limit (LCY)")
+                {
+                    Caption = 'Credit Limit';
+                }
+            }
+        }
+    }
+    
+    var
+        APIErrorMgt: Codeunit "API Error Management";
+    
+    trigger OnInsertRecord(BelowxRec: Boolean): Boolean
+    begin
+        // Validate before insert - returns 400 if validation fails
+        APIErrorMgt.ValidateCustomerForAPI(Rec);
+        exit(true);
+    end;
+    
+    trigger OnModifyRecord(): Boolean
+    begin
+        // Validate before modify - returns 400 if validation fails
+        APIErrorMgt.ValidateCustomerForAPI(Rec);
+        exit(true);
+    end;
+    
+    trigger OnDeleteRecord(): Boolean
+    begin
+        // Check if customer can be deleted - returns 409 if conflict
+        CheckCustomerCanBeDeleted();
+        exit(true);
+    end;
+    
+    local procedure CheckCustomerCanBeDeleted()
+    var
+        CustLedgerEntry: Record "Cust. Ledger Entry";
+        SalesHeader: Record "Sales Header";
+    begin
+        // Check for open transactions
+        CustLedgerEntry.SetRange("Customer No.", Rec."No.");
+        CustLedgerEntry.SetRange(Open, true);
+        if not CustLedgerEntry.IsEmpty then
+            Error('CUSTOMER_HAS_OPEN_ENTRIES:Cannot delete customer with open ledger entries');
+            
+        // Check for pending orders
+        SalesHeader.SetRange("Sell-to Customer No.", Rec."No.");
+        SalesHeader.SetFilter("Document Type", '%1|%2', SalesHeader."Document Type"::Order, SalesHeader."Document Type"::Invoice);
+        if not SalesHeader.IsEmpty then
+            Error('CUSTOMER_HAS_PENDING_ORDERS:Cannot delete customer with pending sales orders');
+    end;
+}
+```
+
+## HTTP Status Code Mapping and Error Categories
+
+```al
+codeunit 50121 "API Error Response Handler"
+{
+    // Demonstrates how different AL errors map to HTTP status codes
+    
+    procedure DemonstrateErrorTypes(var Customer: Record Customer)
+    begin
+        // 400 Bad Request - Validation errors
+        ValidateRequiredData(Customer);
+        
+        // 404 Not Found - Record not found
+        ValidateRecordExists(Customer);
+        
+        // 409 Conflict - Business rule conflicts
+        ValidateBusinessConflicts(Customer);
+        
+        // 422 Unprocessable Entity - Semantic errors
+        ValidateSemanticRules(Customer);
+    end;
+    
+    local procedure ValidateRequiredData(var Customer: Record Customer)
+    begin
+        // These errors result in 400 Bad Request
+        if Customer."No." = '' then
+            Error('Customer number is required');  // 400
+            
+        if Customer.Name = '' then
+            Error('Customer name cannot be empty');  // 400
+            
+        if StrLen(Customer."No.") > 20 then
+            Error('Customer number exceeds maximum length of 20 characters');  // 400
+    end;
+    
+    local procedure ValidateRecordExists(var Customer: Record Customer)
+    var
+        CustomerPostingGroup: Record "Customer Posting Group";
+        PaymentTerms: Record "Payment Terms";
+    begin
+        // These errors result in 400 Bad Request (not 404 - BC limitation)
+        if Customer."Customer Posting Group" <> '' then
+            if not CustomerPostingGroup.Get(Customer."Customer Posting Group") then
+                Error('Customer posting group %1 does not exist', Customer."Customer Posting Group");
+                
+        if Customer."Payment Terms Code" <> '' then
+            if not PaymentTerms.Get(Customer."Payment Terms Code") then
+                Error('Payment terms %1 do not exist', Customer."Payment Terms Code");
+    end;
+    
+    local procedure ValidateBusinessConflicts(var Customer: Record Customer)
+    var
+        ExistingCustomer: Record Customer;
+    begin
+        // These errors typically result in 400 Bad Request
+        // BC doesn't directly support 409 Conflict, but these are conceptually conflicts
+        
+        ExistingCustomer.SetRange("No.", Customer."No.");
+        ExistingCustomer.SetFilter(SystemId, '<>%1', Customer.SystemId);
+        if not ExistingCustomer.IsEmpty then
+            Error('Customer number %1 already exists', Customer."No.");  // Conceptually 409
+    end;
+    
+    local procedure ValidateSemanticRules(var Customer: Record Customer)
+    begin
+        // Complex business rule validation - 400 Bad Request
+        if (Customer."Credit Limit (LCY)" > 50000) and (Customer."Payment Terms Code" = '') then
+            Error('High credit limit customers must have payment terms specified');
+            
+        if Customer.Blocked <> Customer.Blocked::" " then
+            if Customer."Credit Limit (LCY)" > 0 then
+                Error('Blocked customers cannot have credit limit greater than zero');
+    end;
+    
+    // Error formatting for consistent API responses
+    procedure FormatAPIError(ErrorCode: Text; ErrorMessage: Text; ErrorCategory: Text): Text
+    var
+        ErrorJsonObject: JsonObject;
+        ErrorJson: Text;
+    begin
+        // Create structured error response
+        ErrorJsonObject.Add('code', ErrorCode);
+        ErrorJsonObject.Add('message', ErrorMessage);
+        ErrorJsonObject.Add('category', ErrorCategory);
+        ErrorJsonObject.Add('timestamp', CurrentDateTime);
+        ErrorJsonObject.WriteTo(ErrorJson);
+        
+        exit(ErrorJson);
+    end;
+}
+```
+
+## Error Response Examples and Testing
+
+```al
+codeunit 50122 "API Error Testing"
+{
+    // Test various error scenarios to understand response formats
+    
+    [Test]
+    procedure TestValidationErrors()
+    var
+        Customer: Record Customer;
+        APIErrorHandler: Codeunit "API Error Response Handler";
+    begin
+        // Test required field validation
+        Customer.Init();
+        Customer."No." := '';  // Missing required field
+        
+        asserterror APIErrorHandler.DemonstrateErrorTypes(Customer);
+        
+        // Expected response: 400 Bad Request
+        // {
+        //   "error": {
+        //     "code": "BadRequest",
+        //     "message": "Customer number is required"
+        //   }
+        // }
+        
+        Assert.ExpectedError('Customer number is required');
+    end;
+    
+    [Test]
+    procedure TestBusinessRuleViolation()
+    var
+        Customer: Record Customer;
+        APIErrorHandler: Codeunit "API Error Response Handler";
+    begin
+        // Test business rule validation
+        Customer.Init();
+        Customer."No." := 'TEST001';
+        Customer.Name := 'Test Customer';
+        Customer."Credit Limit (LCY)" := 75000;
+        Customer."Payment Terms Code" := '';  // Violates business rule
+        
+        asserterror APIErrorHandler.DemonstrateErrorTypes(Customer);
+        
+        // Expected response: 400 Bad Request
+        // {
+        //   "error": {
+        //     "code": "BadRequest", 
+        //     "message": "High credit limit customers must have payment terms specified"
+        //   }
+        // }
+        
+        Assert.ExpectedError('High credit limit customers must have payment terms specified');
+    end;
+    
+    [Test]
+    procedure TestRecordNotFound()
+    var
+        Customer: Record Customer;
+        APIErrorHandler: Codeunit "API Error Response Handler";
+    begin
+        // Test reference to non-existent record
+        Customer.Init();
+        Customer."No." := 'TEST002';
+        Customer.Name := 'Test Customer';
+        Customer."Customer Posting Group" := 'NONEXISTENT';
+        
+        asserterror APIErrorHandler.DemonstrateErrorTypes(Customer);
+        
+        // Expected response: 400 Bad Request (BC limitation - should be 404)
+        // {
+        //   "error": {
+        //     "code": "BadRequest",
+        //     "message": "Customer posting group NONEXISTENT does not exist"
+        //   }
+        // }
+        
+        Assert.ExpectedError('Customer posting group NONEXISTENT does not exist');
+    end;
+}
+
+// Error response interceptor for custom formatting
+codeunit 50123 "API Error Formatter"
+{
+    [EventSubscriber(ObjectType::Codeunit, Codeunit::"API Error Publisher", 'OnAfterPublishError', '', false, false)]
+    local procedure OnAfterPublishAPIError(ErrorContext: Text; var ErrorPayload: Text)
+    var
+        ErrorDetails: JsonObject;
+        CustomError: JsonObject;
+    begin
+        // Intercept and format API errors for consistent response structure
+        if ErrorDetails.ReadFrom(ErrorPayload) then begin
+            CustomError.Add('timestamp', CurrentDateTime);
+            CustomError.Add('path', ErrorContext);
+            CustomError.Add('error', ErrorDetails);
+            CustomError.Add('apiVersion', 'v2.0');
+            
+            CustomError.WriteTo(ErrorPayload);
+        end;
+    end;
+}
+```
+
+## Implementation Notes
+
+**BC API Error Response Behavior:**
+- Most AL errors return 400 Bad Request status code
+- BC automatically wraps AL Error() calls in OData error format
+- Custom error codes can be embedded in error messages
+- Error details include message, code, and sometimes inner error information
+
+**Error Categories and HTTP Status Mapping:**
+- **400 Bad Request**: Validation errors, missing required fields, format errors
+- **401 Unauthorized**: Authentication failures (handled by BC framework)
+- **403 Forbidden**: Permission denied (handled by BC framework)  
+- **404 Not Found**: Invalid API endpoint (handled by BC framework)
+- **409 Conflict**: Not directly supported - use 400 with descriptive message
+- **422 Unprocessable Entity**: Not directly supported - use 400
+- **500 Internal Server Error**: Unexpected AL runtime errors
+
+**Best Practices:**
+- Use descriptive error messages that help API consumers
+- Include error codes for programmatic error handling
+- Validate data comprehensively before database operations
+- Handle business rule violations gracefully
+- Test error scenarios thoroughly
+- Consider creating custom error response formats for better API experience
+
+**Testing Error Responses:**
+- Use BC Test Toolkit to validate error handling
+- Test all validation scenarios systematically
+- Verify error message clarity and usefulness
+- Ensure consistent error format across API endpoints
+- Monitor error logs for unexpected error patterns