Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation for error codes #421

Merged
merged 20 commits into from
Jul 16, 2020

Conversation

MarinPostma
Copy link
Contributor

@MarinPostma MarinPostma commented Jun 22, 2020

errors.yaml Outdated Show resolved Hide resolved
description: "There was an error in the search."
- code: unsupported_media_type
description: "The payload for the request is not supported by meilisearch. Meilisearch currently only support JSON payloads."
...
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this PR ready for review?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's open for discussion

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does it mean there are missing information?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No all error codes are here, but we can discuss the descriptions

errors.yaml Outdated
- code: open_index
description: "An error occured while trying to open the requested index, ..."
- code: invalid_state
description: "An error occuring when the database is in an invalid state. Deleting the database and reindexing should solve the problem."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "An error occuring when the database is in an invalid state. Deleting the database and reindexing should solve the problem."
description: "An error occurred when the database is in an invalid state. Deleting the database and reindexing should solve the problem."

errors.yaml Outdated
- code: invalid_index_uid
description: "The provided index formatting is wrong, check out our guide on [index creation](link.com)"
- code: open_index
description: "An error occured while trying to open the requested index, ..."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "An error occured while trying to open the requested index, ..."
description: "An error occurred while trying to open the requested index, ..."

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't have any idea to complete the ...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, I don't think it is clear what "opening" an index means

errors.yaml Outdated
description: "All documents must be identified with a unique key. Meilisearch will try to infer the documetn field to use as primary key. If it can't, it has to be specified manually, and this error is returned. See <a href=\"https://docs.meilisearch.com/guides/main_concepts/documents.html#structure\">guide on primary keys</a>."
- code: primary_key_already_present
description: "Error thrown when trying to change the primary key for an index. See [guide on primary keys](https://docs.meilisearch.com/guides/main_concepts/documents.html#structure)."
- code: max_field_limit_exceeded
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- code: max_field_limit_exceeded
- code: max_fields_limit_exceeded

errors.yaml Outdated
- code: primary_key_already_present
description: "Error thrown when trying to change the primary key for an index. See [guide on primary keys](https://docs.meilisearch.com/guides/main_concepts/documents.html#structure)."
- code: max_field_limit_exceeded
description: "The maximum number of fields for a document is 65,535. When this number is exceded, this error is returned."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The maximum number of fields for a document is 65,535. When this number is exceded, this error is returned."
description: "The maximum number of fields for a document is 65,535. When this number is exceeded, this error is returned."

errors.yaml Outdated
- code: document_not_found
description: "The requested document can't be retieved. It either doesn't exists, or the database was left in an inconsistent state."
- code: internal
description: "An error with Meilisearch internals has occured. Check the error message, and fill an issue if necessary."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "An error with Meilisearch internals has occured. Check the error message, and fill an issue if necessary."
description: "An error with MeiliSearch internals has occurred. Check the error message, and open an issue if necessary."

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "An error with Meilisearch internals has occured. Check the error message, and fill an issue if necessary."
description: "MeiliSearch experienced an internal error. Check the error message, and fill an issue if necessary."

errors.yaml Outdated
- code: invalid_token
description: "The provided token is invalid."
- code: maintenance
description: "The Meilisearch instance in under maintenance."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The Meilisearch instance in under maintenance."
description: "The MeiliSearch instance in under maintenance."

errors.yaml Outdated
- code: not_found
description: "The requested ressources could not be found."
- code: payload_too_large
description: "The payload sent to the server was too large. Check out this [guide](https://docs.meilisearch.com/guides/advanced_guides/configuration.html#options) to change the maximum payload size"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The payload sent to the server was too large. Check out this [guide](https://docs.meilisearch.com/guides/advanced_guides/configuration.html#options) to change the maximum payload size"
description: "The payload sent to the server was too large. Check out this [guide](https://docs.meilisearch.com/guides/advanced_guides/configuration.html#options) to change the maximum payload size."

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The payload sent to the server was too large. Check out this [guide](https://docs.meilisearch.com/guides/advanced_guides/configuration.html#options) to change the maximum payload size"
description: "The payload sent to the server was too large. Check out this [guide](https://docs.meilisearch.com/guides/advanced_guides/configuration.html#options) to customize the maximum payload size accepted by MeiliSearch."

errors.yaml Outdated
- code: search_error
description: "There was an error in the search."
- code: unsupported_media_type
description: "The payload for the request is not supported by meilisearch. Meilisearch currently only support JSON payloads."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The payload for the request is not supported by meilisearch. Meilisearch currently only support JSON payloads."
description: "The payload for the request is not supported by MeiliSearch. MeiliSearch currently only supports JSON payloads."

Copy link
Member

@eskombro eskombro Jun 23, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The payload for the request is not supported by meilisearch. Meilisearch currently only support JSON payloads."
description: "The payload content type is not supported by MeiliSearch. Currently MeiliSearch supports only JSON payloads."

Copy link
Member

@eskombro eskombro left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎉

errors.yaml Outdated
---
errors:
- code: create_index
description: "Error relative to index creation, check out our guide on [index creation](link.com)"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "Error relative to index creation, check out our guide on [index creation](link.com)"
description: "An error occurred while trying to create an index, check out our guide on [index creation](link.com)"

errors.yaml Outdated
- code: existing_index
description: "An index with this name already exists, check out our guide on [index creation](link.com)"
- code: invalid_index_uid
description: "The provided index formatting is wrong, check out our guide on [index creation](link.com)"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The provided index formatting is wrong, check out our guide on [index creation](link.com)"
description: "There is an error in the provided index format, check out our guide on [index creation](link.com)"

errors.yaml Outdated
- code: invalid_index_uid
description: "The provided index formatting is wrong, check out our guide on [index creation](link.com)"
- code: open_index
description: "An error occured while trying to open the requested index, ..."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, I don't think it is clear what "opening" an index means

errors.yaml Outdated
- code: invalid_state
description: "An error occuring when the database is in an invalid state. Deleting the database and reindexing should solve the problem."
- code: missing_primary_key
description: "All documents must be identified with a unique key. Meilisearch will try to infer the documetn field to use as primary key. If it can't, it has to be specified manually, and this error is returned. See <a href=\"https://docs.meilisearch.com/guides/main_concepts/documents.html#structure\">guide on primary keys</a>."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "All documents must be identified with a unique key. Meilisearch will try to infer the documetn field to use as primary key. If it can't, it has to be specified manually, and this error is returned. See <a href=\"https://docs.meilisearch.com/guides/main_concepts/documents.html#structure\">guide on primary keys</a>."
description: "All documents must be identified with a unique key. MeiliSearch will try to infer the document field to use it as a primary key. If it can't infer it, the primary key must be specified manually, and this error is returned. See <a href=\"https://docs.meilisearch.com/guides/main_concepts/documents.html#structure\">guide on primary keys</a>."

errors.yaml Outdated
- code: missing_primary_key
description: "All documents must be identified with a unique key. Meilisearch will try to infer the documetn field to use as primary key. If it can't, it has to be specified manually, and this error is returned. See <a href=\"https://docs.meilisearch.com/guides/main_concepts/documents.html#structure\">guide on primary keys</a>."
- code: primary_key_already_present
description: "Error thrown when trying to change the primary key for an index. See [guide on primary keys](https://docs.meilisearch.com/guides/main_concepts/documents.html#structure)."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "Error thrown when trying to change the primary key for an index. See [guide on primary keys](https://docs.meilisearch.com/guides/main_concepts/documents.html#structure)."
description: "Error thrown when trying to modify the primary key of an index, when it has been already set. See [guide on primary keys](https://docs.meilisearch.com/guides/main_concepts/documents.html#structure)."

errors.yaml Outdated
- code: invalid_facet
description: "The facet filter provided with the search is invalid. Check our [guide on faceting](https://docs.meilisearch.com/guides/advanced_guides/faceted_search.html) to troubleshoot."
- code: invalid_filter
description: "The facet filter provided with the search is invalid. Check our [guide on faceting](https://docs.meilisearch.com/guides/advanced_guides/filtering.html) to troubleshoot."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The facet filter provided with the search is invalid. Check our [guide on faceting](https://docs.meilisearch.com/guides/advanced_guides/filtering.html) to troubleshoot."
description: "The filter provided with the search is invalid. Check our [guide on faceting](https://docs.meilisearch.com/guides/advanced_guides/filtering.html) to troubleshoot."

errors.yaml Outdated
- code: bad_request
description: "The request is invalid, check the error message for more information."
- code: document_not_found
description: "The requested document can't be retieved. It either doesn't exists, or the database was left in an inconsistent state."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The requested document can't be retieved. It either doesn't exists, or the database was left in an inconsistent state."
description: "The requested document can't be retrieved. Either it doesn't exist, or the database was left in an inconsistent state."

errors.yaml Outdated
- code: maintenance
description: "The Meilisearch instance in under maintenance."
- code: missing_authorization_header
description: "The requested ressources is protected with an API key, that was not provided in the request header. Check our guide on [authentication](https://docs.meilisearch.com/guides/advanced_guides/authentication.html) for more information."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The requested ressources is protected with an API key, that was not provided in the request header. Check our guide on [authentication](https://docs.meilisearch.com/guides/advanced_guides/authentication.html) for more information."
description: "The requested resources are protected with an authentication system, and no API KEY was provided in the request header. Check our guide on [authentication](https://docs.meilisearch.com/guides/advanced_guides/authentication.html) for more information."

errors.yaml Outdated
- code: missing_authorization_header
description: "The requested ressources is protected with an API key, that was not provided in the request header. Check our guide on [authentication](https://docs.meilisearch.com/guides/advanced_guides/authentication.html) for more information."
- code: missing_header
description: "The header is missing."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The header is missing."
description: "A header is missing in the HTTP request."

errors.yaml Outdated
- code: missing_header
description: "The header is missing."
- code: not_found
description: "The requested ressources could not be found."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The requested ressources could not be found."
description: "The requested resources could not be found."

Replaces `GET` with `POST` in examples for update `searchable-attributes`, `displayed-attributes`, and `accept-new-fields`
@bidoubiwa
Copy link
Contributor

bidoubiwa commented Jun 24, 2020

I don't know if we talked about this but

  • code: create_index
  • code: open_index
  • code: retrieve_document

Are the only errors without a error connotation attached to it.

As we look at the other once:

  • create_index ❌
  • existing_index ✅
  • invalid_index_uid ✅
  • open_index ❌
  • invalid_state ✅
  • missing_primary_key ✅
  • primary_key_already_present ✅
  • max_fields_limit_exceeded ✅
  • missing_document_id ✅
  • invalid_facet ✅
  • invalid_filter ✅
  • bad_parameter ✅
  • bad_request ✅
  • document_not_found ✅
  • internal ✅
  • invalid_token ✅
  • maintenance ✅
  • missing_authorization_header ✅
  • missing_header ✅
  • not_found ✅
  • payload_too_large ✅
  • retrieve_document ❌
  • search_error ✅
  • unsupported_media_type ✅

Could we consider to add the error connotation to it?

  • could_not_create_index
  • could_not_open_index
  • could_not_retrieve_document

Of course this is possibly not important. I say that with the idea that a error code gives you an ultra minimalistic feedback of what happened. Which is the case for all the error codes except those 3.

@MarinPostma
Copy link
Contributor Author

I understand your concern @bidoubiwa, and I remember wanting to append "error" to those errors in the beginning. Those are error code, so it is expected that something went wrong in the process, and in that sense I don't think that prepending "could_not" adds anything, neither does appending "error". This code's purpose is to be read by a computer, and we made them readable simply for devs comfort. What do you think?

@bidoubiwa
Copy link
Contributor

bidoubiwa commented Jun 24, 2020

If it is only meant to be read by computer it is indeed not usefull to add anything. But in this case I would suggest we add a title field in which we describe in a minimalistic way the error. So that I can use that title and not the error code as a header in the error page.

So it's either one or the other. Both are good for me.

errors.yaml Outdated
errors:
- code: create_index
description: "An error occurred while trying to create an index, check out our guide on [index creation](https://docs.meilisearch.com/guides/main_concepts/indexes.html)"
- code: existing_index
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- code: existing_index
- code: index_already_exists

Copy link
Member

@curquiza curquiza Jun 25, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I did not notice it before! We decided this name during a meeting because that's the only one we already use in our code since the v0.11 is out. Please don't change this one 🙏

@curquiza
Copy link
Member

curquiza commented Jun 25, 2020

I agree with @bidoubiwa, this is not clear that these 3 ones are errors.
For me, the could_not as a prefix is ok (better than error as a suffix) and fixes this unclear naming. Except if you have a better suggestion.

When I look at Stripe code error, every naming is clear and means this is an error. I don't see any "non-error" naming like open_index equivalent.

@curquiza
Copy link
Member

curquiza commented Jun 29, 2020

Hello @MarinPostma

We discuss with the team (@tpayet, @eskombro, and @bidoubiwa) about these 3 errors. We would rather rename it as:

  • index_creation_failed
  • index_not_accessible
  • unretrievable_document

We read the error descriptions to chose the naming.
Do you agree? 🙂

@bidoubiwa
Copy link
Contributor

This is still in progress or is the list completed?

@MarinPostma
Copy link
Contributor Author

the list is complete

errors.yaml Show resolved Hide resolved
bidoubiwa
bidoubiwa previously approved these changes Jul 1, 2020
@bidoubiwa bidoubiwa mentioned this pull request Jul 1, 2020
errors.yaml Outdated
- code: index_not_accessible
description: "An internal error occurred while trying to access the requested index."
- code: invalid_state
description: "An error that occurs when the database is in an invalid state. Deleting the database and re indexing should solve the problem."
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "An error that occurs when the database is in an invalid state. Deleting the database and re indexing should solve the problem."
description: "An error that occurs when the database is in an invalid state. Deleting the database and re-indexing should solve the problem."

errors.yaml Outdated
- code: invalid_state
description: "An error that occurs when the database is in an invalid state. Deleting the database and re indexing should solve the problem."
- code: missing_primary_key
description: "All documents must be identified with a unique key. MeiliSearch will try to infer the document field to use it as a primary key. If it can't infer it, the primary key must be specified manually, and this error is returned. . See our [guide on primary keys](https://docs.meilisearch.com/guides/main_concepts/documents.html#structure)."
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "All documents must be identified with a unique key. MeiliSearch will try to infer the document field to use it as a primary key. If it can't infer it, the primary key must be specified manually, and this error is returned. . See our [guide on primary keys](https://docs.meilisearch.com/guides/main_concepts/documents.html#structure)."
description: "All documents must be identified with a unique key. MeiliSearch will try to infer the document field to use it as a primary key. If it can't infer it, the primary key must be specified manually, and this error is returned. See our [guide on primary keys](https://docs.meilisearch.com/guides/main_concepts/documents.html#structure)."

errors.yaml Outdated
- code: missing_primary_key
description: "All documents must be identified with a unique key. MeiliSearch will try to infer the document field to use it as a primary key. If it can't infer it, the primary key must be specified manually, and this error is returned. . See our [guide on primary keys](https://docs.meilisearch.com/guides/main_concepts/documents.html#structure)."
- code: primary_key_already_present
description: "Error thrown when trying to modify the primary key of an index, when it has been already set. See [guide on primary keys](https://docs.meilisearch.com/guides/main_concepts/documents.html#structure)."
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "Error thrown when trying to modify the primary key of an index, when it has been already set. See [guide on primary keys](https://docs.meilisearch.com/guides/main_concepts/documents.html#structure)."
description: "This error is thrown when trying to modify the primary key of an index when it has been already set. See [guide on primary keys](https://docs.meilisearch.com/guides/main_concepts/documents.html#structure)."

errors.yaml Outdated
- code: invalid_token
description: "The provided token is invalid."
- code: maintenance
description: "The MeiliSearch instance in under maintenance."
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The MeiliSearch instance in under maintenance."
description: "The MeiliSearch instance is under maintenance."

errors.yaml Outdated
- code: maintenance
description: "The MeiliSearch instance in under maintenance."
- code: missing_authorization_header
description: "The requested resources is protected with an API key, that was not provided in the request header. Check our guide on [authentication](https://docs.meilisearch.com/guides/advanced_guides/authentication.html) for more information."
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The requested resources is protected with an API key, that was not provided in the request header. Check our guide on [authentication](https://docs.meilisearch.com/guides/advanced_guides/authentication.html) for more information."
description: "The requested resources are protected with an API key, that was not provided in the request header. Check our guide on [authentication](https://docs.meilisearch.com/guides/advanced_guides/authentication.html) for more information."

errors.yaml Outdated
- code: search_error
description: "There was an error in the search."
- code: unsupported_media_type
description: "The payload content type is not supported by MeiliSearch. Currently MeiliSearch supports only JSON payloads."
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: "The payload content type is not supported by MeiliSearch. Currently MeiliSearch supports only JSON payloads."
description: "The payload content type is not supported by MeiliSearch. Currently, MeiliSearch supports only JSON payloads."

@matboivin
Copy link
Contributor

Nice job! Voila! 😄

@bidoubiwa bidoubiwa changed the base branch from master to prepare-v0.12 July 16, 2020 10:36
@bidoubiwa bidoubiwa merged commit 8276a7b into meilisearch:prepare-v0.12 Jul 16, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants