Error format in RPC

According to the JSON-RPC specification, when an RPC call results in an error, the response object must contain an "error" member, which is an object with the following members:

• code: A number that indicates the type of error that occurred. It must be an integer.
• message: A string providing a short description of the error. The message should be short and concise.
• data (optional): Additional information about the error that can be useful for debugging.

You can read more about the error format in the JSON-RPC specification: JSON-RPC 2.0 Specification.

Error handling

JsonRpcBundle implements a standard error handling mechanism for RPC requests, based on the separate ufo-tech/rpc-exceptions package. This package makes it possible to handle errors that occur while executing RPC requests in detail and to return standardized error codes and messages.

Error codes and their meaning

The ufo-tech/rpc-exceptions package provides a list of standard error codes and the corresponding exception classes:

Codes outside the -32768…-32000 range are converted into CustomApplicationException, so the application can use its own error codes.

Parameter errors

Missing required parameters, wrong types, failed DTO creation and #[RPC\Assertions] violations are returned as a single -32602 error with per-parameter messages in error.data:

{
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
        "code": -32602,
        "message": "Invalid Data for call method: user.create",
        "data": {"email": "Required parameter \"email\" not passed"}
    }
}

Errors in the documentation

Exceptions declared in the method's docblock with the @throws tag go into the documentation with their code and message, so the client knows in advance which errors to expect.

Using exceptions in your code

Getting an exception object from a code

use Ufo\RpcError\AbstractRpcErrorException;  
  
$code = -32700;  
$message = 'Some custom error message from rpc server'; // optional  
$rpcException = AbstractRpcErrorException::fromCode($code);  
// returns an instance of RpcJsonParseException::class

Getting an exception object from an array

use Ufo\RpcError\AbstractRpcErrorException;  
  
$data = [  
    'code' => -32600,  
    'message' => 'Some custom error message from rpc server',  
];  
$rpcException = AbstractRpcErrorException::fromArray($data);  
// returns an instance of RpcBadRequestException::class

Getting an exception object from JSON

use Ufo\RpcError\AbstractRpcErrorException;  
  
$data = "{\"code\":-32500,\"message\":\"Some custom error message from rpc server\"}";  
$rpcException = AbstractRpcErrorException::fromJson($data);  
// returns an instance of RpcRuntimeException::class

Tips for developers

If you, as a developer, want to return a specific error that the RPC server will interpret, you should use one of the interfaces provided by the ufo-tech/rpc-exceptions package, or extend a standard exception and follow the error numbering.

However, if no specific handling is needed, the server can handle any error or exception that occurs at the API method execution level, keeping your system stable and reliable.

Additional error data can be passed to the client via error.data: all exceptions of the package (AbstractRpcErrorException implements Ufo\RpcError\IExceptionWithData) have the changeExtraData() / pushToExtraData() methods. You can replace or extend an error globally in a listener for the rpc.error event.