From 02ae4078ca950e11f78440533f1d26b204b0be7f Mon Sep 17 00:00:00 2001 From: Guillaume Mourier Date: Wed, 13 Oct 2021 10:31:25 +0200 Subject: [PATCH] Error Format (#61) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Patch GeoSearch specification to mention technical limit on `desc` ordering around a _geoPoint (#66) * mention decision and expected behavior for a desc ordering around a geoPoint * add desc ordering around a geoPoint as a future possibility * add descending order capability for _geoPoint built-in sort (#77) * Sort (#55) * initialize sort specification * wip specification body * fix typos and details * Add OpenAPI changes * Rename API routes * fix typo * add a part about measuring success * specify metrics to send on Amplitude * add lexicographical order for string type * Typos, invalid_sort error definition * Apply suggestions from code review Co-authored-by: Clémentine Urquizar * remove non correct information about mistyped ranking rule that do not raise error * fix typos from reviews * Update text/0055-sort.md Co-authored-by: gui machiavelli Co-authored-by: Clémentine Urquizar Co-authored-by: gui machiavelli * Initialize draft specification for error object format * reorganize and fix typos * update oas with the new error format * Add full list of errors * Add invalid_geo_field error description * Add task_not_found definition * Add mention of error object fields order in response * Apply suggestions from code review Co-authored-by: gui machiavelli * enhance the missing_primary_key error * add know variants for message for a given error * fix oas * remove invalid_sort variant message for _geoPoint descending order * fix typos * sync new variants with geosearch error handling on ranking rule * Update variants for invalid_filter and invalid_sort regarding geosearch * add missing dot at the end of error message * experiment bump.sh diff fixs * update bump.yml * update errors in oas Co-authored-by: Clémentine Urquizar Co-authored-by: gui machiavelli --- .github/workflows/bump.yml | 1 - open-api.yaml | 58 +- text/0061-error-format-and-definitions.md | 926 ++++++++++++++++++++++ 3 files changed, 955 insertions(+), 30 deletions(-) create mode 100644 text/0061-error-format-and-definitions.md diff --git a/.github/workflows/bump.yml b/.github/workflows/bump.yml index 32fe86e0..25acbae8 100644 --- a/.github/workflows/bump.yml +++ b/.github/workflows/bump.yml @@ -5,7 +5,6 @@ on: branches: - main - develop - jobs: api-diff: if: ${{ github.event_name == 'pull_request' }} diff --git a/open-api.yaml b/open-api.yaml index 0a6ad012..dbe8563a 100644 --- a/open-api.yaml +++ b/open-api.yaml @@ -493,17 +493,17 @@ components: properties: message: type: string - errorCode: + code: type: string - errorType: + type: type: string - errorLink: + link: type: string required: - message - - errorCode - - errorType - - errorLink + - code + - type + - link description: '' parameters: indexUid: @@ -683,10 +683,10 @@ components: examples: Unauthorized: value: - message: You must have an authorization token - errorCode: missing_authorization_header - errorType: authentication_error - errorLink: 'https://docs.meilisearch.com/errors#missing_authorization_header' + message: The X-MEILI-API-KEY header is missing. + code: missing_authorization_header + type: auth + link: 'https://docs.meilisearch.com/errors#missing_authorization_header' '413': description: Payload Too Large content: @@ -696,10 +696,10 @@ components: examples: Payload Too Large: value: - message: Payload reached size limit. - errorCode: payload_too_large - errorType: invalid_request_error - errorLink: 'https://docs.meilisearch.com/errors#payload_too_large' + message: The payload cannot exceed `:payloadSizeLimit`. + code: payload_too_large + type: invalid_request + link: 'https://docs.meilisearch.com/errors#payload_too_large' securitySchemes: apiKey: type: apiKey @@ -817,9 +817,9 @@ paths: Not Found: value: message: Dump `20201001-110357260` not found - errorCode: not_found - errorType: invalid_request_error - errorLink: 'https://docs.meilisearch.com/errors#not_found' + code: dump_not_found + type: invalid_request + link: 'https://docs.meilisearch.com/errors#dump_not_found' parameters: - schema: type: string @@ -924,16 +924,16 @@ paths: examples: Index already exists: value: - message: Index already exists. - errorCode: index_already_exists - errorType: invalid_request_error - errorLink: 'https://docs.meilisearch.com/errors#index_already_exists' + message: Index `:indexUid` already exists. + code: index_already_exists + type: invalid_request + link: 'https://docs.meilisearch.com/errors#index_already_exists' Invalid Index Uid: value: - message: 'Index must have a valid uid; Index uid can be of type integer or string only composed of alphanumeric characters, hyphens (-) and underscores (_).' - errorCode: invalid_index_uid - errorType: invalid_request_error - errorLink: 'https://docs.meilisearch.com/errors#invalid_index_uid' + message: 'Index `:indexUid` is not a valid index uid. Index uid can be an integer or a string containing only alphanumeric characters, hyphens (-) and underscores (_).' + code: invalid_index_uid + type: invalid_request + link: 'https://docs.meilisearch.com/errors#invalid_index_uid' '401': $ref: '#/components/responses/401' parameters: @@ -1002,10 +1002,10 @@ paths: examples: Primary Key Already Present: value: - message: A primary key is already present. It's impossible to update it - errorCode: primary_key_already_present - errorType: invalid_request_error - errorLink: 'https://docs.meilisearch.com/errors#primary_key_already_present' + message: Index `:indexUid` already has a primary key. + code: index_primary_key_already_exists + type: invalid_request + link: 'https://docs.meilisearch.com/errors#index_primary_key_already_exists' '401': $ref: '#/components/responses/401' '404': diff --git a/text/0061-error-format-and-definitions.md b/text/0061-error-format-and-definitions.md new file mode 100644 index 00000000..bbeb5a89 --- /dev/null +++ b/text/0061-error-format-and-definitions.md @@ -0,0 +1,926 @@ +- Title: Error Format and Definitions +- Start Date: 2021-08-13 +- Specification PR: [#61](https://github.com/meilisearch/specifications/pull/61) +- Discovery Issue: [#44](https://github.com/meilisearch/product/issues/44#issuecomment-896121211) + +# Error Format + +## 1. Functional Specification + +### I. Summary + +The error format is updated to no longer contain unnecessary `error` prefix terms in the names of these attributes. e.g. `errorType` becomes `type`. The context is clear enough to understand that this is an `error` object. + +This specification also serves as a reference point for the complete list of API errors that the user may encounter. + +#### Summary Key Points + +- `error` is removed from the attributes name and `type` values. +- An exhaustive list of API errors is defined with their message variants. See Errors List part. + +### II. Motivation + +The motivation is to stabilize the current `error` resource to a version that conforms to our API convention and thus allows future evolutions on a more solid base. This specification avoids adding unnecessary information in the error object's attribute names. + +The second motivation is to describe in an exhaustive way all the errors that the user may encounter during his use of the API. This list will be kept up to date. + +### III. Explanation + +#### Error Format + +##### Attributes + +| Field name | type | Description | +|------------|--------|--------------------------------------------------------------------------| +| message | string | A human-readable message providing context and details about the error. | +| code | string | A short string indicating the error code reported. | +| type | string | The type of error returned. `invalid_request`, `internal`, `auth`. | +| link | string | An URL to the related error-page details for further information. | + +##### Json Response Example + +e.g. 401 Unauthorized Response example + +``` +{ + "message": "authorization header is missing", + "code": "missing_authorization_header", + "type": "auth", + "link": "https://docs.meilisearch.com/errors#missing_authorization_header" +} +``` + +- 💡 The error object fields order must conform to the example. + +##### type enum + +| type | description | +|-----------------|---------------------------------------------------------------------------------------------------| +| invalid_request | This type of error is usually due to a user input error. It is accompanied by an HTTP code `4xx`. | +| internal | Usually, this type of error is returned because the search engine can't operate due to machine or configuration constraints. It can be due to limits being reached, such as the size of the disk, the size limit of an index, etc. It can also be an unexpected error. It is accompanied by an HTTP code `5xx`. | +| auth | This type of error is returned when it comes to authentication and authorization. It is accompanied by an HTTP code `4xx`. | + +--- + +#### Error list + +Following this format, here is the exhaustive list of errors that MeiliSearch can return to an API consumer. This list is updated as MeiliSearch evolves. + +💡 Errors returned asynchronously in a `task` object do not include a definition of the HTTP code and mention Async instead of the HTTP code. An asynchronous error is returned in the payload of the update task. + +# invalid_request type + +## bad_request + +### Context + +This error code is generic. It should not be used. Instead, a clear and precise error code should be determined to guide the user efficiently. + +### Error Definition + +HTTP code `400 Bad Request` + +```json +{ + "message": ":errorMessage", + "code": "bad_request", + "type": "invalid_request", + "link":"https://docs.meilisearch.com/errors#bad_request" +} +``` + +--- + +## index_already_exists + +### Context + +This error happens when a user tries to create an index that already exists. + +### Error Definition + +HTTP Code: `409 Conflict` + +```json +{ + "message": "Index :uid already exists.", + "code": "index_already_exists", + "type": "invalid_request", + "link":"https://docs.meilisearch.com/errors#index_already_exists" +} +``` + +- The `:uid` is inferred when the message is generated. + +--- + +## invalid_index_uid + +### Context + +This error happens when a user tries to create an index with an invalid uid format. + +### Error Definition + +HTTP Code: `400 Bad Request` + +```json +{ + "message": ":uid is not a valid index uid. Index uid can be an integer or a string containing only alphanumeric characters, hyphens (-) and underscores (_).", + "code": "invalid_index_uid", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#invalid_index_uid" +} +``` + +- The `:uid` is inferred when the message is generated. + +--- + +## index_primary_key_already_exists + +### Context + +This error happens when a user tries to update an index primary key while the index already has one primary key. + +### Error Definition + +HTTP Code: `400 Bad Request` + +```json +{ + "message": "Index :uid already has a primary key.", + "code": "index_primary_key_already_exists", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#index_primary_key_already_exists" +} +``` + +--- + +## primary_key_inference_failed + +### Context + +This error occurs when the engine does not find an identifier in the payload documents to define it as the primary key of the index during the inference process when no document has already been inserted. + +### Error Definition + +Async + +```json +{ + "message": "The primary key inference process failed because the engine did not find any fields containing `id` substring in their name. If your document identifier does not contain any `id` substring, you can set the primary key of the index.", + "code": "primary_key_inference_failed", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#primary_key_inference_failed" +} +``` + +--- + +## missing_document_id + +### Context + +This error occurs when the engine does not find the primary key previously defined for the index in the document payload. + +### Error Definition + +Async + +```json +{ + "message": "Document doesn't have a :primaryKey attribute: :documentRepresentation.", + "code": "missing_document_id", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#missing_document_id" +} +``` + +- The `:primaryKey` is inferred when the message is generated. This is the value of the primaryKey attribute of the related index object. +- The `:documentRepresentation` is inferred when the message is generated. + +--- + +## document_fields_limit_reached + +### Context + +The maximum number of fields for a document is `65,535`. When this number is exceeded, this error is returned. This error is returned within a `task` for a `documentsAddition` or `documentsPartial` operation. + +### Error Definition + +Async + +```json +{ + "message": "A document cannot contain more than 65,535 fields.", + "code": "document_fields_limit", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#documents_fields_limit" +} +``` + +--- + +## invalid_ranking_rule + +### Context + +This error occurs when the user specifies a non-existent ranking rule, a malformed custom ranking rule in the settings payload, or tries to specify a custom ranking rule on the reserved keywords `_geo` and `_geoDistance`. + +### Error Definition + +Async + +#### Variant: Sending an inexistent ranking rule or an invalid custom ranking rule syntax. + +```json +{ + "message": ":rankingRule ranking rule is invalid. Valid ranking rules are Words, Typo, Sort, Proximity, Attribute, Exactness and custom ranking rules.", + "code": "invalid_ranking_rule", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#invalid_ranking_rule" +} +``` + +- The `:rankingRule` is inferred when the message is generated. It could be a misspelled ranking rule like `Wards` instead of `Words` or a custom ranking rule expressed with a syntax error. + + +#### Variant: Specifying a custom ranking rule on reserved fields `_geo` or `_geoDistance` + +```json +{ + "message": ":reservedKeyword is a reserved keyword and thus can't be used as a ranking rule.", + ... +} +``` + +- The `:reservedKeyword` is inferred when the message is generated. + +#### Variant: Specifying a custom ranking rule on reserved expression `_geoPoint` + +```json +{ + "message": ":reservedKeyword is a reserved keyword and thus can't be used as a ranking rule. :reservedKeyword can only be used for sorting at search time.", + ... +} +``` + +- The `:reservedKeyword` is inferred when the message is generated. + +#### Variant: Specifying a custom ranking rule on reserved expression `_geoRadius` + +```json +{ + "message": ":reservedKeyword is a reserved keyword and thus can't be used as a ranking rule. :reservedKeyword can only be used for filtering at search time.", + ... +} +``` + +- The `:reservedKeyword` is inferred when the message is generated. + +--- + +## invalid_filter + +### Context + +This error occurs at search time when there is a syntax error in the `filter` parameter, when an attribute expressed in the filter is not defined in the `filterableAttributes` list or when a reserved keywords like `_geo`, `_geoDistance` and `_geoPoint` is used as a filter. + +### Error Definition + +HTTP Code: `400 Bad Request` + +#### Variant: Filtering on a non filterable attribute + +```json +{ + "message": "Attribute :attribute is not filterable. Available filterable attributes are: :filterableAttributes.", + "code": "invalid_filter", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#invalid_filter" +} +``` + +- The `:attribute` is inferred when the message is generated. +- The `:filterableAttributes` is inferred when the message is generated. It contains the list of filterable attributes separated by a comma. `filterableAttribute1, filterableAttribute2, ...` + +#### Variant: Using `_geoDistance` as a filter expression + +```json +{ + "message": ":reservedKeyword is a reserved keyword and thus can't be used as a filter expression.", + ... +} +``` + +- The `:reservedKeyword` is inferred when the message is generated. + +#### Variant: Using `_geo` or `_geoPoint` as a filter expression + +```json +{ + "message": ":reservedKeyword is a reserved keyword and thus can't be used as a filter expression. Use the _geoRadius(latitude, longitude, distance) built-in rule to filter on _geo field coordinates.", + ... +} +``` + +- The `:reservedKeyword` is inferred when the message is generated. + +#### Variant: Invalid syntax for the `filter` parameter + +```json +{ + "message": "Invalid syntax for the filter parameter: :syntaxErrorHelper.", + ... +} +``` + +- The `:syntaxErrorHelper` is inferred when the message is generated. + +--- + +## invalid_sort + +### Context + +This error occurs at search time when there is a syntax error in the `sort` parameter, when an attribute expressed in the sort is not defined in the `sortableAttributes` list, sort at search time while the `sort` ranking rule is missing from the settings, or using reserved keywords like `_geo`, `_geoDistance` and `_geoRadius` as a sort expression. + +### Error Definition: + +HTTP Code: `400 Bad Request` + +#### Variant: Sorting on a non sortable attribute + +```json +{ + "message": "Attribute :attribute is not sortable. Available sortable attributes are: :sortableAttributes.", + "code": "invalid_sort", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#invalid_sort" +} +``` + +- The `:attribute` is inferred when the message is generated. +- The `:sortableAttributes` is inferred when the message is generated. It contains the list of sortable attributes separated by a comma. `sortableAttribute1, sortableAttribute2, ...` + +#### Variant: Using `_geoDistance` as a sort expression + +```json +{ + "message": ":reservedKeyword is a reserved keyword and thus can't be used as a sort expression.", + ... +} +``` + +- The `:reservedKeyword` is inferred when the message is generated. + +#### Variant: Using `_geo` or `_geoRadius` as a sort expression +```json +{ + "message": ":reservedKeyword is a reserved keyword and thus can't be used as a sort expression. Use the _geoPoint(latitude, longitude) built-in rule to sort on _geo field coordinates.", + ... +} +``` + +- The `:reservedKeyword` is inferred when the message is generated. + +#### Variant: Invalid syntax for the `sort`parameter + +```json +{ + "message": "Invalid syntax for the sort parameter: :syntaxErrorHelper.", + ... +} +``` + +- The `:syntaxErrorHelper` is inferred when the message is generated. + +#### Variant: Specifying `sort` at search time while the sort ranking rule isn't set in the ranking rules settings + +```json +{ + "message": "The sort ranking rule must be specified in the ranking rules settings to use the sort parameter at search time.", + ... +} +``` + +--- + +## invalid_geo_field + +### Context + +This error occurs when the `_geo` field of a document payload is not valid. + +### Error Definition + +```json +{ + "message": "The document with the id: `:documentId` contains an invalid _geo field: :syntaxErrorHelper.", + "code": "invalid_geo_field", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#invalid_geo_field" +} + +``` + +- The `:documentId` is inferred when the error message is generated. +- The `:syntaxErrorHelper` is inferred when the error message is generated. + +--- + +## payload_too_large + +### Context + +This error occurs when the size of the payload sent exceeds the limit set by the server. The user can correct this error by reducing the payload size or increasing the limit with [this configuration variable](https://docs.meilisearch.com/reference/features/configuration.html#payload-limit-size) + +### Error Definition + +HTTP Code: `413 Payload Too Large` + +```json +{ + "message": "The payload cannot exceed :payloadSizeLimit.", + "code": "payload_too_large", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#payload_too_large" +} +``` + +- The `:payloadSizeLimit` is inferred when the message is generated. e.g. `100Mb` by default. + +--- + +## not_found + +### Context + +This error code is generic. It should not be used. Instead, a clear and precise error code should be determined. + +--- + +## index_not_found + +### Context + +This error happens when a requested index can't be found. + +### Error Definition + +HTTP Code: `404 Not Found` + +```json +{ + "message": "Index :indexUid not found.", + "code": "index_not_found", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#index_not_found" +} +``` + +- The `:indexUid` is inferred when the message is generated. + +--- + +## document_not_found + +## Context + +This error happens when a requested document can't be found. + +## Error Definition + +HTTP Code: `404 Not Found` + +```json +{ + "message": "Document :documentId not found.", + "code": "document_not_found", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#document_not_found" +} +``` + +- The `:documentId` is inferred when the message is generated. + +--- + +## dump_not_found + +### Context + +This error happens when a requested dump can't be found. + +### Error Definition + +HTTP Code: `404 Not Found` + +```json +{ + "message": "Dump :dumpId not found.", + "code": "dump_not_found", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#dump_not_found" +} +``` + +- The `:dumpId` is inferred when the message is generated. + +--- + +## task_not_found + +#### Context + +This error happens when a requested task can't be found. + +#### Error Definition + +HTTP Code: `404 Not Found` + +```json +{ + "message": "Task :taskUid not found.", + "code": "task_not_found", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#task_not_found" +} +``` + +- The `:taskUid` is inferred when the message is generated. + +--- + +## dump_already_processing + +### Context + +This error occurs when the user tries to launch the creation of a new dump while a creation is already being processed. + +### Error Definition + +Http Code: `409 Conflict` + +```json +{ + "message": "A dump is already processing. You must wait until the current process is finished before requesting another dump.", + "code": "dump_already_processing", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#dump_already_processing" +} +``` + +--- + +## invalid_content_type + +### Context + +This error occurs when the provided content-type is not handled by the API method. + +### Error Definition + +HTTP Code: `415 Unsupported Media Type` + +```json +{ + "message": "The Content-Type :contentType is invalid. Accepted values for the Content-Type header are: :contentTypeList.", + "code": "invalid_content_type", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#invalid_content_type" +} +``` + +- The `:contentTypeList` is inferred when the message is generated. The values are separated by a `,` char. e.g. `application/json`, `text/csv`. + +--- + +## missing_content_type + +### Context + +This error occurs when the Content-Type header is missing. + +### Error Definition + +HTTP Code: `415 Unsupported Media Type` + +```json +{ + "message": "A Content-Type header is missing. Accepted values for the Content-Type header are: :contentTypeList.", + "code": "missing_content_type", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#missing_content_type" +} +``` + +- The `:contentTypeList` is inferred when the message is generated. The values are separated by a `,` char. e.g. `application/json`, `text/csv`. + +--- + +## missing_payload + +### Context + +This error occurs when the client does not provide a mandatory payload to the request. + +### Error Definition + +HTTP Code: `400 Bad Request` + +```json +{ + "message": "A :payloadType payload is missing.", + "code": "missing_payload", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#missing_payload" +} +``` + +- The `:payloadType` is inferred when the message is generated. e.g. `json`, `ndjson`, `csv` + +--- + +## malformed_payload + +### Context + +This error occurs when the format sent in the payload is malformed. The payload contains a syntax error. + +### Error Definition + +HTTP Code: `400 Bad Request` + +```json +{ + "message": "The :payloadType payload provided is malformed. :syntaxErrorHelper.", + "code": "malformed_payload", + "type": "invalid_request", + "link": "https://docs.meilisearch.com/errors#malformed_payload" +} +``` + +- The `:payloadType` is inferred when the message is generated. e.g. `json`, `ndjson`, `csv` +- The `:syntaxErrorHelper` is inferred when the message is generated. + +--- + +# internal type + +## internal + +### Context + +This error code occurs when an unknown and undetermined error has occurred at the server. This is a error that should not happen. + +### Error Definition + +HTTP Code: `500 Internal Server Error` + +```json +{ + "message": "An internal error has occurred. :reason.", + "code": "internal", + "type": "internal", + "link": "https://docs.meilisearch.com/errors#internal" +} +``` + +- The `:reason` is inferred when the message is generated. e.g. `Internal: decoding failed` + +--- + +## index_creation_failed + +### Context + +This error occurs when an index creation could not be completed for various reasons. + +### Error Definition + +HTTP Code: `500 Internal Server Error` + +```json +{ + "message": "The creation of the :uid index has failed due to :reason.", + "code": "index_creation_failed", + "type": "internal", + "link": "https://docs.meilisearch.com/errors#index_creation_failed" +} +``` + +- The `:reason` is inferred when the message is generated. e.g. `Write Permission denied` + +--- + +## index_not_accessible + +### Context + + This error occurs when an index cannot be accessed for various reasons. + +### Error Definition + +HTTP Code: `500 Internal Server Error` + +```json +{ + "message": "The index :uid can't be accessed due to :reason.", + "code": "index_not_accessible", + "type": "internal", + "link": "https://docs.meilisearch.com/errors#index_not_accessible" +} +``` + +- The `:reason` is inferred when the message is generated. e.g. `Read Permission denied` + +--- + +## unretrievable_document + +### Context + +This error occurs when a document cannot be found in the system due to an inconsistent state that can occur for several reasons. + +### Error Definition + +HTTP Code: `500 Internal Server Error` + +```json +{ + "message": "The document :documentId is unretrievable due to :reason.", + "code": "unretrievable_document", + "type": "internal", + "link": "https://docs.meilisearch.com/errors#unretrievable_document" +} +``` + +- The `documentId` is inferred when the message is generated. +- The `:reason` is inferred when the message is generated. + +--- + +## invalid_state + +### Context + +This error occurs when the database is in an inconsistent state due to an uncontrolled internal error. + +### Error Definition + +HTTP Code: `500 Internal Server Error` + +```json +{ + "message": "The database is in an invalid state.", + "code": "invalid_state", + "type": "internal", + "link": "https://docs.meilisearch.com/errors#invalid_state" +} +``` + +--- + +## dump_process_failed + +### Context + +This error occurs during the dump creation process. The dump creation was interrupted for various reasons. + +### Error Definition + +Async + +```json +{ + "message": "The creation of the dump :dumpId failed due to :reason.", + "code": "dump_process_failed", + "type": "internal", + "link": "https://docs.meilisearch.com/errors#dump_process_failed" +} +``` + +- The `:reason` is inferred when the message is generated. e.g. `Permission denied` + +--- + +## database_size_limit_reached + +### Context + +This error occurs when the user tries to add documents and the maximum size of the database reaches the limit. The user can correct this error by increasing the database size limit. + +### Error Definition + +HTTP code `500 Internal Server Error` + +```json +{ + "message": "Maximum database size of :databaseSizeLimit has been reached.", + "code": "database_size_limit_reached", + "type": "internal", + "link": "https://docs.meilisearch.com/errors#database_size_limit_reached" +} +``` + +- The `:databaseSizeLimit` is inferred when the message is generated. e.g. `100GiB` + +--- + +## no_space_left_on_device + +### Context + +This error occurs when the host system partition has reached its maximum capacity and no longer accepts writes. + +### Error Definition + +HTTP Code: `500 Internal Server Error` + +```json +{ + "message": "There is no more space left on the device. Consider increasing the size of the disk/partition.", + "code": "no_space_left_on_device", + "type": "internal", + "link": "https://docs.meilisearch.com/errors#no_space_left_on_device" +} +``` + +--- + +## invalid_store_file + +### Context + +This error occurs when the `data.ms` folder is in an inconsistent state. It can happen for various reasons. An .mdb file can be corrupted, the data.ms folder has been replaced by a file, etc. + +### Error Definition + +HTTP Code: `500 Internal Server Error` + +```json +{ + "message": "The database file is in an invalid state.", + "code": "invalid_store_file", + "type": "internal", + "link": "https://docs.meilisearch.com/errors#invalid_store_file" +} +``` + +--- + +# auth type + +## missing_authorization_header + +### Context + +This error occurs when the route is protected, and the `X-MEILI-API-KEY` header is not provided. + +### Error Definition + +HTTP Code: `401 Unauthorized` + +```json +{ + "message": "The X-MEILI-API-KEY header is missing.", + "code": "missing_authorization_header", + "type": "auth", + "link": "https://docs.meilisearch.com/errors#missing_authorization_header" +} +``` + +--- + +## invalid_api_key + +### Context + +This error occurs when the route is protected, and the value of the `X-MEILI-API-KEY` header does not allow access to the resource. + +### Error Definition + +HTTP Code: `403 Forbidden` + +```json +{ + "message": "The provided API key is invalid.", + "code": "invalid_api_key", + "type": "auth", + "link": "https://docs.meilisearch.com/errors#invalid_api_key" +} +``` + +--- + +## 2. Technical details +N/A + +## 3. Future Possibilities + +- Add a `parameter` attribute in the `error` object to indicate which request parameter caused an error. +- Add more specific error types. For example, explode internal errors into several distinct types. \ No newline at end of file