Error Functions

Introduction

This set of custom functions provides a standardized approach to error handling in FileMaker solutions. Instead of dealing with raw error codes, these functions create and manipulate structured JSON error objects that contain detailed information about errors, making them easier to track, log, and handle.

These functions are part of the errorCfx repository from Proof+Geist, available as open source under the MIT license.

The error objects typically include:

• code: The numeric error code
• text: A human-readable description of the error
• scriptName: The name of the script where the error occurred
• scriptStep: The specific script step that generated the error
• lineNumber: Line number in the script (when available)
• environment: Context information about the environment

Dependencies

These error functions rely on the following miscellaneous utility functions:

• getScriptEnvironment - Provides system and script context information
• JSON.isValid - Validates JSON format
• null - Returns a proper null value

Functions

error.GetCode(errorObject)

Description: Returns the error code from a given error object. Returns 0 if there is no error, or the numeric error code if an error exists.

Parameters:

• errorObject: An error object as JSON

Return:

• The numeric error code (0 if no error)

Example:

Let (
    [
        $error = error.Set(101; "Record not found"; "Find Customer")
    ];
    error.GetCode($error)
)
// Returns: 101

error.GetLast(customText)

Description: Returns an error object based on the information in FileMaker's error flags. If the LastError flag is set to 5499, it will return the custom error object found on line 4 of the LastErrorDetail flag.

Parameters:

• customText (optional): Replaces the default error message

Dependencies:

• error.Text - For error message lookup
• JSON.isValid - For validating custom error JSON
• null - For null handling
• getScriptEnvironment - For context information

Return:

• A JSON error object with details about the last error

Example:

// After an operation that might generate an error
Let (
    [
        $error = error.GetLast("Failed to create invoice")
    ];
    // Use $error for error handling
    $error
)
// Returns: {"code": 401, "text": "Failed to create invoice", "scriptName": "Create Invoice", "scriptStep": "Create Record", "lineNumber": 25, "environment": {...}}

error.Set(errorCode; text; scriptStep)

Description: Creates a structured error object with the specified error code, message text, and script step information.

Parameters:

• errorCode: The numeric code for the error
• text: Custom error message (uses default error text if empty)
• scriptStep: The name of the script step where the error occurred

Dependencies:

• error.Text - For default error messages
• getScriptEnvironment - For context information

Return:

• A JSON error object

Example:

Let (
    [
        $error = error.Set(101; "Customer record could not be found"; "Find Customer")
    ];
    // Use $error for logging or display to users
    $error
)
// Returns: {"code": 101, "text": "Customer record could not be found", "scriptName": "Current Script Name", "scriptStep": "Find Customer", "environment": {...}}

error.SetFromDAPI(DAPIResponseObject; scriptStep)

Description: Creates an error object from a Data API response object, adding the script step where the error occurred.

Parameters:

• DAPIResponseObject: The FileMaker Data API response object
• scriptStep: The name of the script step where the error occurred

Return:

• A JSON error object with details from the Data API response

Example:

Let (
    [
        // Sample Data API error response
        $response = "{\"messages\":[{\"code\":\"102\",\"message\":\"Field is missing\"}]}";
        $error = error.SetFromDAPI($response; "Create Record via API")
    ];
    $error
)
// Returns: {"code": "102", "message": "Field is missing", "scriptStep": "Create Record via API"}

error.SetFromHttpResponse(response; scriptStep)

Description: Creates an error object from an HTTP response. If the response is successful (ok is true), it returns a no-error object with code 0.

Parameters:

• response: An HTTP response object containing at least an "ok" property
• scriptStep: The name of the script step where the error occurred

Dependencies:

• error.Set - For creating the error object

Return:

• A JSON error object with details from the HTTP response, including HTTP status code and response body for errors

Example:

Let (
    [
        // Sample HTTP error response
        $response = "{\"ok\": false, \"code\": 404, \"status\": \"Not Found\", \"body\": \"{\\\"error\\\":\\\"Resource not found\\\"}\"}";
        $error = error.SetFromHttpResponse($response; "Fetch Customer API")
    ];
    $error
)
// Returns: {"code": -2, "text": "Status Code: 404. Not Found", "scriptName": "Current Script Name", "scriptStep": "Fetch Customer API", "httpStatus": 404, "httpResponseBody": {"error": "Resource not found"}}

error.Text(errorCode)

Description: Looks up the description for a FileMaker error code. This function contains a comprehensive list of FileMaker error codes and their corresponding descriptions.

Parameters:

• errorCode: A FileMaker error code (number)

Return:

• A string describing the error associated with the error code

Example:

Let (
    [
        $description = error.Text(101)
    ];
    $description
)
// Returns: "Record is missing"

Usage Tips

1. Consistent Error Handling: Use these functions to standardize error handling across your FileMaker solution.

2. Error Logging: Store error objects in a log table for troubleshooting.

3. Chaining: These functions can be chained together - for example, use error.GetLast() to capture an error and error.GetCode() to check the error code:

   If (error.GetCode(error.GetLast()) ≠ 0;
       // Handle error
   )

4. Custom Errors: Create custom error objects with error.Set() when you need to generate your own error conditions.

5. Integration with Other Functions: These error functions are designed to work with the miscellaneous utility functions for complete error handling capabilities.