From b270aac8270f03d8c3c573c75fcf4df476bfc646 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Fri, 29 Sep 2023 15:00:53 +0200 Subject: [PATCH 1/4] Add explanation about errors --- .../3.10/develop/error-codes-and-meanings.md | 70 ++++++++++++++++++- .../3.11/develop/error-codes-and-meanings.md | 70 ++++++++++++++++++- .../3.12/develop/error-codes-and-meanings.md | 70 ++++++++++++++++++- 3 files changed, 201 insertions(+), 9 deletions(-) diff --git a/site/content/3.10/develop/error-codes-and-meanings.md b/site/content/3.10/develop/error-codes-and-meanings.md index 4ca4365e10..62de2773e0 100644 --- a/site/content/3.10/develop/error-codes-and-meanings.md +++ b/site/content/3.10/develop/error-codes-and-meanings.md @@ -2,9 +2,73 @@ title: Error codes and meanings menuTitle: Error codes and meanings weight: 275 -description: '' +description: >- + An error reply from ArangoDB servers contain a code, error number, and message + and you can look up additional information for a specific kind of error pageToc: - maxHeadlineLevel: 2 + maxHeadlineLevel: 3 archetype: default --- -{{% error-codes %}} \ No newline at end of file +{{< description >}} + +## Numbers, names, and descriptions of errors + +When an error occurs in an operation of an ArangoDB server, the +[HTTP REST API](http/_index.md) responds to a request with with an +**HTTP status code** like `400 Bad Request`, `401 Unauthorized`, +`503 Service Unavailable`, or similar. This code is typically also included in +the body of the response, specifically the `code` attribute, along with the +`error` attribute set to `true`. + +``` +HTTP/1.1 401 Unauthorized +... + +{"code":401,"error":true,"errorNum":11,"errorMessage":"not authorized to execute this request"} +``` + +The **error code** only indicates the broad category of an error, based on the +status codes defined by the HTTP protocol. + +A more detailed **error number** is provided in the `errorNum` attribute. +Error numbers are specific to ArangoDB. Each ArangoDB error kind has a number, +a unique name, an error message, and a description. + +The **error message** is a brief description of the error and provided in the +`errorMessage` attribute. + +The **error name** is not visible in the HTTP API response. The name for the +error with the number `11` is `ERROR_FORBIDDEN`, for instance. Error names are +used in code to refer to an error kind, in the server's own code as well as in +other code like drivers. In the [JavaScript API](javascript-api/_index.md), the +`@arangodb` module maps error names to error numbers: + +```js +require("@arangodb").errors.ERROR_FORBIDDEN +``` + +```json +{ + "code" : 11, + "message" : "forbidden" +} +``` + +Note that the error message in the HTTP API response deviates from the above +shown message ("not authorized to execute this request" versus "forbidden"). +ArangoDB does not necessarily return the error message as defined internally but +can override it in order to provide more details. You should therefore check +against the error number in your own code and never rely on the error message, +as it can be different in under different circumstances for the same error kind. + +An **error description** is a more detailed description of the error kind than +the error message. It is not visible in the HTTP API response. It is mainly +used to provide context for developers. + +## List of error codes + +In the following, you find the error kinds that exist in ArangoDB, grouped into +categories. The format is `number - message` for headlines and the error +descriptions as the text. + +{{% error-codes %}} diff --git a/site/content/3.11/develop/error-codes-and-meanings.md b/site/content/3.11/develop/error-codes-and-meanings.md index 4ca4365e10..62de2773e0 100644 --- a/site/content/3.11/develop/error-codes-and-meanings.md +++ b/site/content/3.11/develop/error-codes-and-meanings.md @@ -2,9 +2,73 @@ title: Error codes and meanings menuTitle: Error codes and meanings weight: 275 -description: '' +description: >- + An error reply from ArangoDB servers contain a code, error number, and message + and you can look up additional information for a specific kind of error pageToc: - maxHeadlineLevel: 2 + maxHeadlineLevel: 3 archetype: default --- -{{% error-codes %}} \ No newline at end of file +{{< description >}} + +## Numbers, names, and descriptions of errors + +When an error occurs in an operation of an ArangoDB server, the +[HTTP REST API](http/_index.md) responds to a request with with an +**HTTP status code** like `400 Bad Request`, `401 Unauthorized`, +`503 Service Unavailable`, or similar. This code is typically also included in +the body of the response, specifically the `code` attribute, along with the +`error` attribute set to `true`. + +``` +HTTP/1.1 401 Unauthorized +... + +{"code":401,"error":true,"errorNum":11,"errorMessage":"not authorized to execute this request"} +``` + +The **error code** only indicates the broad category of an error, based on the +status codes defined by the HTTP protocol. + +A more detailed **error number** is provided in the `errorNum` attribute. +Error numbers are specific to ArangoDB. Each ArangoDB error kind has a number, +a unique name, an error message, and a description. + +The **error message** is a brief description of the error and provided in the +`errorMessage` attribute. + +The **error name** is not visible in the HTTP API response. The name for the +error with the number `11` is `ERROR_FORBIDDEN`, for instance. Error names are +used in code to refer to an error kind, in the server's own code as well as in +other code like drivers. In the [JavaScript API](javascript-api/_index.md), the +`@arangodb` module maps error names to error numbers: + +```js +require("@arangodb").errors.ERROR_FORBIDDEN +``` + +```json +{ + "code" : 11, + "message" : "forbidden" +} +``` + +Note that the error message in the HTTP API response deviates from the above +shown message ("not authorized to execute this request" versus "forbidden"). +ArangoDB does not necessarily return the error message as defined internally but +can override it in order to provide more details. You should therefore check +against the error number in your own code and never rely on the error message, +as it can be different in under different circumstances for the same error kind. + +An **error description** is a more detailed description of the error kind than +the error message. It is not visible in the HTTP API response. It is mainly +used to provide context for developers. + +## List of error codes + +In the following, you find the error kinds that exist in ArangoDB, grouped into +categories. The format is `number - message` for headlines and the error +descriptions as the text. + +{{% error-codes %}} diff --git a/site/content/3.12/develop/error-codes-and-meanings.md b/site/content/3.12/develop/error-codes-and-meanings.md index 4ca4365e10..62de2773e0 100644 --- a/site/content/3.12/develop/error-codes-and-meanings.md +++ b/site/content/3.12/develop/error-codes-and-meanings.md @@ -2,9 +2,73 @@ title: Error codes and meanings menuTitle: Error codes and meanings weight: 275 -description: '' +description: >- + An error reply from ArangoDB servers contain a code, error number, and message + and you can look up additional information for a specific kind of error pageToc: - maxHeadlineLevel: 2 + maxHeadlineLevel: 3 archetype: default --- -{{% error-codes %}} \ No newline at end of file +{{< description >}} + +## Numbers, names, and descriptions of errors + +When an error occurs in an operation of an ArangoDB server, the +[HTTP REST API](http/_index.md) responds to a request with with an +**HTTP status code** like `400 Bad Request`, `401 Unauthorized`, +`503 Service Unavailable`, or similar. This code is typically also included in +the body of the response, specifically the `code` attribute, along with the +`error` attribute set to `true`. + +``` +HTTP/1.1 401 Unauthorized +... + +{"code":401,"error":true,"errorNum":11,"errorMessage":"not authorized to execute this request"} +``` + +The **error code** only indicates the broad category of an error, based on the +status codes defined by the HTTP protocol. + +A more detailed **error number** is provided in the `errorNum` attribute. +Error numbers are specific to ArangoDB. Each ArangoDB error kind has a number, +a unique name, an error message, and a description. + +The **error message** is a brief description of the error and provided in the +`errorMessage` attribute. + +The **error name** is not visible in the HTTP API response. The name for the +error with the number `11` is `ERROR_FORBIDDEN`, for instance. Error names are +used in code to refer to an error kind, in the server's own code as well as in +other code like drivers. In the [JavaScript API](javascript-api/_index.md), the +`@arangodb` module maps error names to error numbers: + +```js +require("@arangodb").errors.ERROR_FORBIDDEN +``` + +```json +{ + "code" : 11, + "message" : "forbidden" +} +``` + +Note that the error message in the HTTP API response deviates from the above +shown message ("not authorized to execute this request" versus "forbidden"). +ArangoDB does not necessarily return the error message as defined internally but +can override it in order to provide more details. You should therefore check +against the error number in your own code and never rely on the error message, +as it can be different in under different circumstances for the same error kind. + +An **error description** is a more detailed description of the error kind than +the error message. It is not visible in the HTTP API response. It is mainly +used to provide context for developers. + +## List of error codes + +In the following, you find the error kinds that exist in ArangoDB, grouped into +categories. The format is `number - message` for headlines and the error +descriptions as the text. + +{{% error-codes %}} From aeef17d40d47ad105605b01310d2ac08038c1206 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Fri, 29 Sep 2023 15:02:45 +0200 Subject: [PATCH 2/4] 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 --- .../layouts/shortcodes/error-codes.md | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/site/themes/arangodb-docs-theme/layouts/shortcodes/error-codes.md b/site/themes/arangodb-docs-theme/layouts/shortcodes/error-codes.md index 5ba220d6bb..d816a72249 100644 --- a/site/themes/arangodb-docs-theme/layouts/shortcodes/error-codes.md +++ b/site/themes/arangodb-docs-theme/layouts/shortcodes/error-codes.md @@ -1,14 +1,16 @@ -{{ $pageVersion := .Page.Store.Get "versionShort" }} +{{- $pageVersion := .Page.Store.Get "versionShort" }} +{{- $dataFolderByVersion := index site.Data $pageVersion }} +{{- $data := index $dataFolderByVersion "errors" }} +{{- $basePage := .Page.RelPermalink }} +{{- range $data }} +{{- if index . "group" }} -{{ $dataFolderByVersion := index site.Data $pageVersion }} -{{ $data := index $dataFolderByVersion "errors"}} +### {{ .group }} + +{{ else }} + +#### {{ .code }} - {{ .name }} {#{{ .code }}} -{{ $basePage := .Page.RelPermalink }} -{{ range $data }} - {{ if index . "group" }} -## {{ .group }} - {{ else }} -#### {{ .code }} - {{ .name }}

{{ .desc }}

-{{ end }} -{{ end }} \ No newline at end of file +{{- end }} +{{- end }} From 472079cf835e31f1eec517f72ad2bd4bde5b3f5f Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Fri, 29 Sep 2023 15:12:57 +0200 Subject: [PATCH 3/4] 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 --- site/themes/arangodb-docs-theme/static/css/theme.css | 1 + 1 file changed, 1 insertion(+) diff --git a/site/themes/arangodb-docs-theme/static/css/theme.css b/site/themes/arangodb-docs-theme/static/css/theme.css index 464f78eed8..871707e9e1 100644 --- a/site/themes/arangodb-docs-theme/static/css/theme.css +++ b/site/themes/arangodb-docs-theme/static/css/theme.css @@ -1271,6 +1271,7 @@ article.default, article.chapter, article.home { hgroup > h1, article > h2, article > h3, article > h4, article > h5, article > h6 { color: var(--HEADERS-COLOR); font-weight: var(--TYPOGRAPHY-BOLD-TEXT); + overflow-wrap: break-word; } hgroup > h1, From 762026aed849e276643805c90ff486bed162065e Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Tue, 10 Oct 2023 16:24:51 +0200 Subject: [PATCH 4/4] Apply suggestions from review --- .../3.10/develop/error-codes-and-meanings.md | 14 ++++++++------ .../3.11/develop/error-codes-and-meanings.md | 14 ++++++++------ .../3.12/develop/error-codes-and-meanings.md | 14 ++++++++------ 3 files changed, 24 insertions(+), 18 deletions(-) diff --git a/site/content/3.10/develop/error-codes-and-meanings.md b/site/content/3.10/develop/error-codes-and-meanings.md index 62de2773e0..6337fd9a16 100644 --- a/site/content/3.10/develop/error-codes-and-meanings.md +++ b/site/content/3.10/develop/error-codes-and-meanings.md @@ -14,7 +14,7 @@ archetype: default ## Numbers, names, and descriptions of errors When an error occurs in an operation of an ArangoDB server, the -[HTTP REST API](http/_index.md) responds to a request with with an +[HTTP REST API](http/_index.md) responds to a request with an **HTTP status code** like `400 Bad Request`, `401 Unauthorized`, `503 Service Unavailable`, or similar. This code is typically also included in the body of the response, specifically the `code` attribute, along with the @@ -37,11 +37,13 @@ a unique name, an error message, and a description. The **error message** is a brief description of the error and provided in the `errorMessage` attribute. -The **error name** is not visible in the HTTP API response. The name for the -error with the number `11` is `ERROR_FORBIDDEN`, for instance. Error names are -used in code to refer to an error kind, in the server's own code as well as in -other code like drivers. In the [JavaScript API](javascript-api/_index.md), the -`@arangodb` module maps error names to error numbers: +Error names are used in code to refer to an error kind, in the server's own code +as well as in other code like drivers. For instance, the name for the error with +the number `11` is `ERROR_FORBIDDEN`. The **error name** is not visible in the +HTTP API response. + +In the [JavaScript API](javascript-api/_index.md), the `@arangodb` module maps +error names to objects with the error number and message: ```js require("@arangodb").errors.ERROR_FORBIDDEN diff --git a/site/content/3.11/develop/error-codes-and-meanings.md b/site/content/3.11/develop/error-codes-and-meanings.md index 62de2773e0..6337fd9a16 100644 --- a/site/content/3.11/develop/error-codes-and-meanings.md +++ b/site/content/3.11/develop/error-codes-and-meanings.md @@ -14,7 +14,7 @@ archetype: default ## Numbers, names, and descriptions of errors When an error occurs in an operation of an ArangoDB server, the -[HTTP REST API](http/_index.md) responds to a request with with an +[HTTP REST API](http/_index.md) responds to a request with an **HTTP status code** like `400 Bad Request`, `401 Unauthorized`, `503 Service Unavailable`, or similar. This code is typically also included in the body of the response, specifically the `code` attribute, along with the @@ -37,11 +37,13 @@ a unique name, an error message, and a description. The **error message** is a brief description of the error and provided in the `errorMessage` attribute. -The **error name** is not visible in the HTTP API response. The name for the -error with the number `11` is `ERROR_FORBIDDEN`, for instance. Error names are -used in code to refer to an error kind, in the server's own code as well as in -other code like drivers. In the [JavaScript API](javascript-api/_index.md), the -`@arangodb` module maps error names to error numbers: +Error names are used in code to refer to an error kind, in the server's own code +as well as in other code like drivers. For instance, the name for the error with +the number `11` is `ERROR_FORBIDDEN`. The **error name** is not visible in the +HTTP API response. + +In the [JavaScript API](javascript-api/_index.md), the `@arangodb` module maps +error names to objects with the error number and message: ```js require("@arangodb").errors.ERROR_FORBIDDEN diff --git a/site/content/3.12/develop/error-codes-and-meanings.md b/site/content/3.12/develop/error-codes-and-meanings.md index 62de2773e0..6337fd9a16 100644 --- a/site/content/3.12/develop/error-codes-and-meanings.md +++ b/site/content/3.12/develop/error-codes-and-meanings.md @@ -14,7 +14,7 @@ archetype: default ## Numbers, names, and descriptions of errors When an error occurs in an operation of an ArangoDB server, the -[HTTP REST API](http/_index.md) responds to a request with with an +[HTTP REST API](http/_index.md) responds to a request with an **HTTP status code** like `400 Bad Request`, `401 Unauthorized`, `503 Service Unavailable`, or similar. This code is typically also included in the body of the response, specifically the `code` attribute, along with the @@ -37,11 +37,13 @@ a unique name, an error message, and a description. The **error message** is a brief description of the error and provided in the `errorMessage` attribute. -The **error name** is not visible in the HTTP API response. The name for the -error with the number `11` is `ERROR_FORBIDDEN`, for instance. Error names are -used in code to refer to an error kind, in the server's own code as well as in -other code like drivers. In the [JavaScript API](javascript-api/_index.md), the -`@arangodb` module maps error names to error numbers: +Error names are used in code to refer to an error kind, in the server's own code +as well as in other code like drivers. For instance, the name for the error with +the number `11` is `ERROR_FORBIDDEN`. The **error name** is not visible in the +HTTP API response. + +In the [JavaScript API](javascript-api/_index.md), the `@arangodb` module maps +error names to objects with the error number and message: ```js require("@arangodb").errors.ERROR_FORBIDDEN