Error handling 

Error handling can be configured on site level and is automatically dependent on the current site and language.

Currently, there are two error handler implementations and the option to write a custom handler:

The configuration consists of two parts:

  • The HTTP error status code that should be handled
  • The error handler configuration

You can define one error handler per HTTP error code and add a generic one that serves all error pages.

Add custom error handling.

Properties 

These properties apply to all error handlers.

errorCode
Type
int
Example
404

The HTTP (error) status code to handle. The predefined list contains the most common errors. A free definition of other error codes is also possible. The special value 0 will take care of all errors.

errorHandler
Type
string / enum
Example
Fluid

Define how to handle these errors:

  • Fluid for rendering a Fluid template
  • Page for fetching content from a page
  • PHP for a custom implementation

Trigger an error page from an extension 

\TYPO3\CMS\Frontend\Controller\ErrorController builds the response for an error. It looks up the error handler that the site configures for the status code. Where the site configures none, it falls back to the error page of TYPO3. So an extension that reports an error through this controller gets the error handling of the site.

Any status code with customErrorAction() 

New in version 14.2 Feature: #108904 - Add generic error action for custom HTTP status codes in ErrorController

ErrorController::customErrorAction() reports a status code of your choice, with a title and a message of your own. Use it for a code that the methods for the fixed codes do not cover, for example HTTP 429:

EXT:my_extension/Classes/Controller/DownloadController.php 
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use Psr\Http\Message\ServerRequestInterface;
use TYPO3\CMS\Core\Http\PropagateResponseException;
use TYPO3\CMS\Frontend\Controller\ErrorController;

final readonly class DownloadController
{
  public function __construct(
    private ErrorController $errorController,
  ) {}

  public function downloadAction(ServerRequestInterface $request): never
  {
    $response = $this->errorController->customErrorAction(
      $request,
      429,
      'Too many requests',
      'You have requested too many downloads.',
      'Rate limit of 10 downloads per hour reached',
    );
    throw new PropagateResponseException($response, 1791205354);
  }
}
Copied!

After the request, the status code, the title, and the message, the method takes three optional arguments. $technicalReason is a detail that TYPO3 appends to the message as Reason: <technicalReason>. $reasons reaches the error handler of the site. $errorCode is a number that the error page shows next to the message.

A request that accepts application/json receives a JSON response carrying the technical reason, instead of an HTML page.

Configure an error handler for the status code to render the page of the site instead of the error page of TYPO3. The errorCode property accepts any code, so a site can answer a 429 with a Fluid template of its own.