Skip to content

Commit f841b09

Browse files
Simran-BSimran-B
authored
Improve error codes reference (#253)
* Add explanation about errors * Override headline anchors for error codes Use the error number only, not the full headline text for anchor. Fix headline level to not leave a gap between h2 and h4 * Wrap very long headlines mid-word if they would overflow This should only affect headlines that contain unusually long words without spaces but not wrap mid-word for normal headlines * Apply suggestions from review
1 parent 5716f74 commit f841b09

File tree

5 files changed

+221
-20
lines changed

5 files changed

+221
-20
lines changed

‎site/content/3.10/develop/error-codes-and-meanings.md‎

Lines changed: 69 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,75 @@
22
title: Error codes and meanings
33
menuTitle: Error codes and meanings
44
weight: 275
5-
description: ''
5+
description: >-
6+
An error reply from ArangoDB servers contain a code, error number, and message
7+
and you can look up additional information for a specific kind of error
68
pageToc:
7-
maxHeadlineLevel: 2
9+
maxHeadlineLevel: 3
810
archetype: default
911
---
10-
{{% error-codes %}}
12+
{{< description >}}
13+
14+
## Numbers, names, and descriptions of errors
15+
16+
When an error occurs in an operation of an ArangoDB server, the
17+
[HTTP REST API](http/_index.md) responds to a request with an
18+
**HTTP status code** like `400 Bad Request`, `401 Unauthorized`,
19+
`503 Service Unavailable`, or similar. This code is typically also included in
20+
the body of the response, specifically the `code` attribute, along with the
21+
`error` attribute set to `true`.
22+
23+
```
24+
HTTP/1.1 401 Unauthorized
25+
...
26+
27+
{"code":401,"error":true,"errorNum":11,"errorMessage":"not authorized to execute this request"}
28+
```
29+
30+
The **error code** only indicates the broad category of an error, based on the
31+
status codes defined by the HTTP protocol.
32+
33+
A more detailed **error number** is provided in the `errorNum` attribute.
34+
Error numbers are specific to ArangoDB. Each ArangoDB error kind has a number,
35+
a unique name, an error message, and a description.
36+
37+
The **error message** is a brief description of the error and provided in the
38+
`errorMessage` attribute.
39+
40+
Error names are used in code to refer to an error kind, in the server's own code
41+
as well as in other code like drivers. For instance, the name for the error with
42+
the number `11` is `ERROR_FORBIDDEN`. The **error name** is not visible in the
43+
HTTP API response.
44+
45+
In the [JavaScript API](javascript-api/_index.md), the `@arangodb` module maps
46+
error names to objects with the error number and message:
47+
48+
```js
49+
require("@arangodb").errors.ERROR_FORBIDDEN
50+
```
51+
52+
```json
53+
{
54+
"code" : 11,
55+
"message" : "forbidden"
56+
}
57+
```
58+
59+
Note that the error message in the HTTP API response deviates from the above
60+
shown message ("not authorized to execute this request" versus "forbidden").
61+
ArangoDB does not necessarily return the error message as defined internally but
62+
can override it in order to provide more details. You should therefore check
63+
against the error number in your own code and never rely on the error message,
64+
as it can be different in under different circumstances for the same error kind.
65+
66+
An **error description** is a more detailed description of the error kind than
67+
the error message. It is not visible in the HTTP API response. It is mainly
68+
used to provide context for developers.
69+
70+
## List of error codes
71+
72+
In the following, you find the error kinds that exist in ArangoDB, grouped into
73+
categories. The format is `number - message` for headlines and the error
74+
descriptions as the text.
75+
76+
{{% error-codes %}}

‎site/content/3.11/develop/error-codes-and-meanings.md‎

Lines changed: 69 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,75 @@
22
title: Error codes and meanings
33
menuTitle: Error codes and meanings
44
weight: 275
5-
description: ''
5+
description: >-
6+
An error reply from ArangoDB servers contain a code, error number, and message
7+
and you can look up additional information for a specific kind of error
68
pageToc:
7-
maxHeadlineLevel: 2
9+
maxHeadlineLevel: 3
810
archetype: default
911
---
10-
{{% error-codes %}}
12+
{{< description >}}
13+
14+
## Numbers, names, and descriptions of errors
15+
16+
When an error occurs in an operation of an ArangoDB server, the
17+
[HTTP REST API](http/_index.md) responds to a request with an
18+
**HTTP status code** like `400 Bad Request`, `401 Unauthorized`,
19+
`503 Service Unavailable`, or similar. This code is typically also included in
20+
the body of the response, specifically the `code` attribute, along with the
21+
`error` attribute set to `true`.
22+
23+
```
24+
HTTP/1.1 401 Unauthorized
25+
...
26+
27+
{"code":401,"error":true,"errorNum":11,"errorMessage":"not authorized to execute this request"}
28+
```
29+
30+
The **error code** only indicates the broad category of an error, based on the
31+
status codes defined by the HTTP protocol.
32+
33+
A more detailed **error number** is provided in the `errorNum` attribute.
34+
Error numbers are specific to ArangoDB. Each ArangoDB error kind has a number,
35+
a unique name, an error message, and a description.
36+
37+
The **error message** is a brief description of the error and provided in the
38+
`errorMessage` attribute.
39+
40+
Error names are used in code to refer to an error kind, in the server's own code
41+
as well as in other code like drivers. For instance, the name for the error with
42+
the number `11` is `ERROR_FORBIDDEN`. The **error name** is not visible in the
43+
HTTP API response.
44+
45+
In the [JavaScript API](javascript-api/_index.md), the `@arangodb` module maps
46+
error names to objects with the error number and message:
47+
48+
```js
49+
require("@arangodb").errors.ERROR_FORBIDDEN
50+
```
51+
52+
```json
53+
{
54+
"code" : 11,
55+
"message" : "forbidden"
56+
}
57+
```
58+
59+
Note that the error message in the HTTP API response deviates from the above
60+
shown message ("not authorized to execute this request" versus "forbidden").
61+
ArangoDB does not necessarily return the error message as defined internally but
62+
can override it in order to provide more details. You should therefore check
63+
against the error number in your own code and never rely on the error message,
64+
as it can be different in under different circumstances for the same error kind.
65+
66+
An **error description** is a more detailed description of the error kind than
67+
the error message. It is not visible in the HTTP API response. It is mainly
68+
used to provide context for developers.
69+
70+
## List of error codes
71+
72+
In the following, you find the error kinds that exist in ArangoDB, grouped into
73+
categories. The format is `number - message` for headlines and the error
74+
descriptions as the text.
75+
76+
{{% error-codes %}}

‎site/content/3.12/develop/error-codes-and-meanings.md‎

Lines changed: 69 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,75 @@
22
title: Error codes and meanings
33
menuTitle: Error codes and meanings
44
weight: 275
5-
description: ''
5+
description: >-
6+
An error reply from ArangoDB servers contain a code, error number, and message
7+
and you can look up additional information for a specific kind of error
68
pageToc:
7-
maxHeadlineLevel: 2
9+
maxHeadlineLevel: 3
810
archetype: default
911
---
10-
{{% error-codes %}}
12+
{{< description >}}
13+
14+
## Numbers, names, and descriptions of errors
15+
16+
When an error occurs in an operation of an ArangoDB server, the
17+
[HTTP REST API](http/_index.md) responds to a request with an
18+
**HTTP status code** like `400 Bad Request`, `401 Unauthorized`,
19+
`503 Service Unavailable`, or similar. This code is typically also included in
20+
the body of the response, specifically the `code` attribute, along with the
21+
`error` attribute set to `true`.
22+
23+
```
24+
HTTP/1.1 401 Unauthorized
25+
...
26+
27+
{"code":401,"error":true,"errorNum":11,"errorMessage":"not authorized to execute this request"}
28+
```
29+
30+
The **error code** only indicates the broad category of an error, based on the
31+
status codes defined by the HTTP protocol.
32+
33+
A more detailed **error number** is provided in the `errorNum` attribute.
34+
Error numbers are specific to ArangoDB. Each ArangoDB error kind has a number,
35+
a unique name, an error message, and a description.
36+
37+
The **error message** is a brief description of the error and provided in the
38+
`errorMessage` attribute.
39+
40+
Error names are used in code to refer to an error kind, in the server's own code
41+
as well as in other code like drivers. For instance, the name for the error with
42+
the number `11` is `ERROR_FORBIDDEN`. The **error name** is not visible in the
43+
HTTP API response.
44+
45+
In the [JavaScript API](javascript-api/_index.md), the `@arangodb` module maps
46+
error names to objects with the error number and message:
47+
48+
```js
49+
require("@arangodb").errors.ERROR_FORBIDDEN
50+
```
51+
52+
```json
53+
{
54+
"code" : 11,
55+
"message" : "forbidden"
56+
}
57+
```
58+
59+
Note that the error message in the HTTP API response deviates from the above
60+
shown message ("not authorized to execute this request" versus "forbidden").
61+
ArangoDB does not necessarily return the error message as defined internally but
62+
can override it in order to provide more details. You should therefore check
63+
against the error number in your own code and never rely on the error message,
64+
as it can be different in under different circumstances for the same error kind.
65+
66+
An **error description** is a more detailed description of the error kind than
67+
the error message. It is not visible in the HTTP API response. It is mainly
68+
used to provide context for developers.
69+
70+
## List of error codes
71+
72+
In the following, you find the error kinds that exist in ArangoDB, grouped into
73+
categories. The format is `number - message` for headlines and the error
74+
descriptions as the text.
75+
76+
{{% error-codes %}}

‎site/themes/arangodb-docs-theme/layouts/shortcodes/error-codes.md‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
1-
{{ $pageVersion := .Page.Store.Get "versionShort" }}
1+
{{- $pageVersion := .Page.Store.Get "versionShort" }}
2+
{{- $dataFolderByVersion := index site.Data $pageVersion }}
3+
{{- $data := index $dataFolderByVersion "errors" }}
4+
{{- $basePage := .Page.RelPermalink }}
5+
{{- range $data }}
6+
{{- if index . "group" }}
27

3-
{{ $dataFolderByVersion := index site.Data $pageVersion }}
4-
{{ $data := index $dataFolderByVersion "errors"}}
8+
### {{ .group }}
9+
10+
{{ else }}
11+
12+
#### {{ .code }} - {{ .name }} {#{{ .code }}}
513

6-
{{ $basePage := .Page.RelPermalink }}
7-
{{ range $data }}
8-
{{ if index . "group" }}
9-
## {{ .group }}
10-
{{ else }}
11-
#### {{ .code }} - {{ .name }}
1214
<p>{{ .desc }}</p>
13-
{{ end }}
14-
{{ end }}
15+
{{- end }}
16+
{{- end }}

‎site/themes/arangodb-docs-theme/static/css/theme.css‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1298,6 +1298,7 @@ article.notfound {
12981298
hgroup > h1, article > h2, article > h3, article > h4, article > h5, article > h6 {
12991299
color: var(--HEADERS-COLOR);
13001300
font-weight: var(--TYPOGRAPHY-BOLD-TEXT);
1301+
overflow-wrap: break-word;
13011302
}
13021303

13031304
hgroup > h1,

0 commit comments

Comments
 (0)