docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/json-rpc-bundle/error_handling.md
new file +98
ā0
1
+
# Error format in RPC
2
+
3
+
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:
4
+
5
+
- **code**: A number that indicates the type of error that occurred. It must be an integer.
6
+
- **message**: A string providing a short description of the error. The message should be short and concise.
7
+
- **data** (optional): Additional information about the error that can be useful for debugging.
8
+
9
+
You can read more about the error format in the JSON-RPC specification: [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification#error_object).
10
+
11
+
## Error handling
12
+
13
+
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.
14
+
15
+
### Error codes and their meaning
16
+
17
+
The `ufo-tech/rpc-exceptions` package provides a list of standard error codes and the corresponding exception classes:
18
+
19
+
| Code | Class | Description |
20
+
| --- | --- | --- |
21
+
| -32700 | `RpcJsonParseException` | The server received invalid JSON |
22
+
| -32600 | `RpcBadRequestException` | Invalid request object (including `jsonrpc` ā `"2.0"`, an empty batch, batch disabled) |
23
+
| -32601 | `RpcMethodNotFoundExceptionRpc` | The method does not exist or is not available in this API group / version |
24
+
| -32602 | `RpcBadParamException`, `ConstraintsImposedException` | Invalid method parameters |
25
+
| -32603 | `RpcInternalException` | Internal JSON-RPC error |
26
+
| -32500 | `RpcRuntimeException` | Procedure execution error |
27
+
| -32400 | `RpcLogicException` | Logic error in the application (for example, the method is locked by `#[RPC\Lock]`) |
28
+
| -32401 | `RpcTokenNotSentException` | Token not sent (HTTP 401) |
29
+
| -32403 | `RpcInvalidTokenException` | Invalid token |
30
+
| -32404 | `RpcDataNotFoundException` | Data not found |
31
+
| -32300 | `RpcAsyncRequestException` | Asynchronous request error |
32
+
| -32301 | `RpcInvalidBatchRequestExceptions` | Batch request error |
33
+
| -32000 | `RpcCustomServerException` | Implementation-defined server error |
34
+
35
+
Codes outside the `-32768ā¦-32000` range are converted into `CustomApplicationException`, so the application can use its own error codes.
36
+
37
+
### Parameter errors
38
+
39
+
Missing required parameters, wrong types, failed DTO creation and [`#[RPC\Assertions]`](/docs/api/json-rpc-bundle/add_rpc_service/assertions) violations are returned as a single `-32602` error with per-parameter messages in `error.data`:
40
+
41
+
```json
42
+
{
43
+
"jsonrpc": "2.0",
44
+
"id": 1,
45
+
"error": {
46
+
"code": -32602,
47
+
"message": "Invalid Data for call method: user.create",
48
+
"data": {"email": "Required parameter \"email\" not passed"}
49
+
}
50
+
}
51
+
```
52
+
53
+
### Errors in the documentation
54
+
55
+
Exceptions declared in the method's docblock with the `@throws` tag go into the [documentation](/docs/api/json-rpc-bundle/documentation) with their code and message, so the client knows in advance which errors to expect.
56
+
57
+
### Using exceptions in your code
58
+
59
+
#### Getting an exception object from a code
60
+
61
+
```php
62
+
use Ufo\RpcError\AbstractRpcErrorException;
63
+
64
+
$code = -32700;
65
+
$message = 'Some custom error message from rpc server'; // optional
66
+
$rpcException = AbstractRpcErrorException::fromCode($code);
67
+
// returns an instance of RpcJsonParseException::class
68
+
```
69
+
70
+
#### Getting an exception object from an array
71
+
```php
72
+
use Ufo\RpcError\AbstractRpcErrorException;
73
+
74
+
$data = [
75
+
'code' => -32600,
76
+
'message' => 'Some custom error message from rpc server',
77
+
];
78
+
$rpcException = AbstractRpcErrorException::fromArray($data);
79
+
// returns an instance of RpcBadRequestException::class
80
+
```
81
+
82
+
#### Getting an exception object from JSON
83
+
84
+
```php
85
+
use Ufo\RpcError\AbstractRpcErrorException;
86
+
87
+
$data = "{\"code\":-32500,\"message\":\"Some custom error message from rpc server\"}";
88
+
$rpcException = AbstractRpcErrorException::fromJson($data);
89
+
// returns an instance of RpcRuntimeException::class
90
+
```
91
+
92
+
### Tips for developers
93
+
94
+
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.
95
+
96
+
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.
97
+
98
+
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`](/docs/api/json-rpc-bundle/functionality/events) event.