Skip to main content

Exception Handling Structure

This document outlines how exceptions or errors are thrown by the server and the structure of the JSON responses returned to the client.

Default Response​

For users who are not administrators or do not have permission to access debug information, the server returns a simplified error response. This response includes a translated error message and a code that identifies the type of error.

Example​

{
    "message": "Error message translated",
    "code": "code name"
}

Debug Mode Response​

When debug mode is enabled, the server provides additional details in the error response. This detailed response includes the exception class name, a stack trace, and the file and line number where the exception was thrown. This information is useful for developers to diagnose and fix issues.

Example​

{
    "message": "The subscription has ended",
    "code": "subscription.hasEnded",
    "debug": {
        "exception": "SubscriptionHasEndedException",
        "trace": [
            // Framework default trace...
        ],
        "file": "...\\modules\\Subscription\\src\\CASubscriptionService.php",
        "line": 49
    }
}

Explanation​

  • message: A user-friendly error message, translated to the appropriate language.
  • code: A unique code identifying the type of error.
  • debug: Additional debugging information.
    • exception: The class name of the exception.
    • trace: The stack trace showing the sequence of method calls leading to the exception.
    • file: The file in which the exception was thrown.
    • line: The line number where the exception was thrown.

HTTP Status Codes​

In addition to the JSON response, the server also returns appropriate HTTP status codes to indicate the type of error. Here are some common status codes:

  • 400 Bad Request: The client sent an invalid request.
  • 401 Unauthorized: The client failed to authenticate with the server.
  • 402 Payment Required: The server says to access the source, need to pay
  • 403 Forbidden: The client authenticated but does not have permission to access the requested resource.
  • 404 Not Found: The requested resource does not exist.
  • 500 Internal Server Error: A generic error occurred on the server.

By providing both a clear JSON response and appropriate HTTP status codes, the server ensures that clients can understand and handle errors effectively.