You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/book/v4/core-features/exceptions.md
+35-21Lines changed: 35 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,48 +2,59 @@
2
2
3
3
## What are exceptions?
4
4
5
-
Exceptions are a powerful mechanism for handling errors and other exceptional conditions that may occur during the execution of a script.
6
-
They provide a way to manage errors in a structured and controlled manner, separating error-handling code from regular code.
5
+
Exceptions are a powerful mechanism for handling errors and other exceptional conditions that may occur during the
6
+
execution of a script.
7
+
They provide a way to manage errors in a structured and controlled manner, separating error-handling code from regular
8
+
code.
7
9
8
10
## How we use exceptions?
9
11
10
-
When it comes to handling exceptions, **DotKernel API** relies on the usage of easy-to-understand, problem-specific exceptions.
12
+
When it comes to handling exceptions, **DotKernel API** relies on the usage of easy-to-understand, problem-specific
13
+
exceptions.
11
14
12
15
Out-of-the-box we provide the following custom exceptions:
13
16
14
-
### `BadRequestException` thrown when:
17
+
### `BadRequestException` thrown when
15
18
16
-
* client tries to create/update resource, but the data from the request is invalid/incomplete (example: client tries to create an account, but does not send the required `identity` field)
17
-
18
-
### `ConflictException` thrown when:
19
+
* client tries to create/update resource, but the data from the request is invalid/incomplete (example: client tries to
20
+
create an account, but does not send the required `identity` field)
19
21
20
-
* resource cannot be created because a different resource with the same identifier already exists (example: cannot change existing user's identity because another user with the same identity already exists)
21
-
* resource cannot change its state because it is already in the specified state (example: user cannot be activated because it is already active)
22
+
### `ConflictException` thrown when
22
23
23
-
### `ExpiredException` thrown when:
24
+
* resource cannot be created because a different resource with the same identifier already exists (example: cannot
25
+
change existing user's identity because another user with the same identity already exists)
26
+
* resource cannot change its state because it is already in the specified state (example: user cannot be activated
27
+
because it is already active)
28
+
29
+
### `ExpiredException` thrown when
24
30
25
31
* resource cannot be accessed because it expired (example: account activation link)
26
32
* resource cannot be accessed because it has been consumed (example: one-time password)
27
33
28
-
### `ForbiddenException` thrown when:
34
+
### `ForbiddenException` thrown when
29
35
30
-
* resource cannot be accessed by the authenticated client (example: client authenticated as regular user sends a `GET /admin` request)
36
+
* resource cannot be accessed by the authenticated client (example: client authenticated as regular user sends
37
+
a `GET /admin` request)
31
38
32
-
### `MethodNotAllowedException` thrown when:
39
+
### `MethodNotAllowedException` thrown when
33
40
34
-
* client tries to interact with a resource via an invalid HTTP request method (example: client sends a `PATCH /avatar` request)
41
+
* client tries to interact with a resource via an invalid HTTP request method (example: client sends a `PATCH /avatar`
42
+
request)
35
43
36
-
### `NotFoundException` thrown when:
44
+
### `NotFoundException` thrown when
37
45
38
-
* client tries to interact with a resource that does not exist on the server (example: client sends a `GET /resource-does-not-exist` request)
46
+
* client tries to interact with a resource that does not exist on the server (example: client sends
47
+
a `GET /resource-does-not-exist` request)
39
48
40
-
### `UnauthorizedException` thrown when:
49
+
### `UnauthorizedException` thrown when
41
50
42
-
* resource cannot be accessed because the client is not authenticated (example: unauthenticated client sends a `GET /admin` request)
51
+
* resource cannot be accessed because the client is not authenticated (example: unauthenticated client sends
52
+
a `GET /admin` request)
43
53
44
54
## How it works?
45
55
46
-
During a request, if there is no uncaught exception **DotKernel API** will return a JSON response with the data provided by the handler that handled the request.
56
+
During a request, if there is no uncaught exception **DotKernel API** will return a JSON response with the data provided
57
+
by the handler that handled the request.
47
58
48
59
Else, it will build and send a response based on the exception thrown:
49
60
@@ -58,7 +69,9 @@ Else, it will build and send a response based on the exception thrown:
58
69
59
70
## How to extend?
60
71
61
-
In this example we will create a custom exception called `CustomException`, place it next to the already existing custom exceptions (you can use your preferred location) and finally return a custom HTTP status code when `CustomException` is encountered.
72
+
In this example we will create a custom exception called `CustomException`, place it next to the already existing custom
73
+
exceptions (you can use your preferred location) and finally return a custom HTTP status code when `CustomException` is
74
+
encountered.
62
75
63
76
### Step 1: Create exception file
64
77
@@ -93,7 +106,8 @@ Save and close the file.
93
106
94
107
### Step 3: Test for failure
95
108
96
-
Access your API's home page URL and make sure it returns `500 Internal Server Error` HTTP status code and the following content:
109
+
Access your API's home page URL and make sure it returns `500 Internal Server Error` HTTP status code and the following
0 commit comments