Errors handling enhancement

[gmourier]

🤖 API Diff Put the link of the GitHub comment generated by bump.sh if generated; Apply the OpenApi label n/a

---

Summary

meilisearch/meilisearch#3246

• Replace bad_request linked to a property/parameter with dedicated error codes
• Replace generic missing_parameter with dedicated error codes
• Rename some error codes to follow a predictable naming convention.
• Move no_space_left_on_device coming from the internal type to a newly introduced system type
  • Add too_many_open_files error code to system
  • Add io_error error code to system
• Replace immutable_field with dedicated error codes (used for the /keys API and /indexes API on the PATCH method)
• CATCH-UP spec bad_request variant when an unknown field is given
• Add invalid_task_index_uids error code
• Remove old mentions of "this :placeholder is inferred when the message is generated"

---

Changes

code property

Swap API

POST /swap-indexes

• duplicate_index_found → invalid_swap_duplicate_index_found ✅ [RENAME]
• Sending an indexes array not containing exactly 2 indexUids for a swap operation object returns a bad_request error -> invalid_swap_indexes ✅ [NEW]
• Sending an invalid index uid in the indexes array returns an invalid_swap_indexes error ✅
• Omitting the indexes array in a swap payload returns a missing_swap_indexes error ✅ [NEW]

Index API

GET /indexes

• limit parameter error bad_request → invalid_index_limit ✅ [NEW]
• offset parameter error bad_request → invalid_index_offset ✅ [NEW]

GET /indexes/:indexUid

• Sending an invalid index uid in the :indexUid path parameter returns an invalid_index_uid error ✅

POST /indexes

• bad_request when uid is missing in the payload → missing_index_uid ✅ [NEW]
• Sending a value with a different type than string or null for primaryKey will return a bad_request error → invalid_index_primary_key ✅ [NEW]

PATCH /indexes/:indexUid

• Sending an invalid index uid in the :indexUid path parameter returns an invalid_index_uid error ✅
• Sending a value with a different type than string or null for primaryKey will return a bad_request error → invalid_index_primary_key ✅ [NEW]
• Modifying the uid property returns an immutable_index_uid error ✅ [NEW]
• Modifying the createdAt property returns an immutable_index_created_at error ✅ [NEW]
• Modifying the updatedAt property returns an immutable_index_updated_at error ✅ [NEW]

DELETE /indexes/:indexUid

• Sending an invalid index uid in the :indexUid path parameter returns an invalid_index_uid error ✅

Documents API

GET /indexes/:indexUid/documents

• Sending an invalid index uid in the :indexUid path parameter returns an invalid_index_uid ✅
• fields parameter error bad_request → invalid_document_fields ✅ [NEW]
• limit parameter error bad_request → invalid_document_limit ✅ [NEW]
• offset parameter error bad_request → invalid_document_offset ✅ [NEW]

GET /indexes/:indexUid/documents/:documentId

• Sending an invalid index uid in the :indexUid path parameter returns an invalid_index_uid ✅
• fields parameter error bad_request → invalid_document_fields ✅ [NEW]

POST/PUT /indexes/:indexUid/documents

• Sending an invalid index uid in the :indexUid path parameter returns an invalid_index_uid ✅
• ?primaryKey parameter error bad_request → invalid_index_primary_key ✅ [NEW]
  • Newly introduced error codes for the primary key inferences are described here Robustify Primary Key Inference - Update related errors #208

DELETE /indexes/:indexUid/documents

• Sending an invalid index uid in the :indexUid path parameter returns an invalid_index_uid ✅

DELETE /indexes/:indexUid/documents/:documentId

• Sending an invalid index uid in the :indexUid path parameter returns an invalid_index_uid ✅

POST /indexes/:indexUid/documents/delete-batch

• Sending an invalid index uid in the :indexUid path parameter returns an invalid_index_uid ✅

Search API ✅

GET/POST /indexes/:indexUid/search

• Sending an invalid index uid in the :indexUid path parameter returns an invalid_index_uid ✅

bad_request replaced by specific error codes per parameter👇

• invalid_search_q [NEW]
• invalid_search_offset [NEW]
• invalid_search_limit [NEW]
• invalid_search_page [NEW]
• invalid_search_hits_per_page [NEW]
• invalid_search_attributes_to_retrieve [NEW]
• invalid_search_attributes_to_crop [NEW]
• invalid_search_crop_length [NEW]
• invalid_search_attributes_to_highlight [NEW]
• invalid_search_show_matches_position [NEW]
• invalid_filter -> invalid_search_filter [RENAME]
• invalid_sort -> invalid_search_sort [RENAME]
• invalid_search_facets [NEW]
• invalid_search_highlight_pre_tag [NEW]
• invalid_search_highlight_post_tag [NEW]
• invalid_search_crop_marker [NEW]
• invalid_search_matching_strategy [NEW]

Settings API ✅

• Sending an invalid index uid in the :indexUid path parameter returns an invalid_index_uid ✅

bad_request replaced by specific error codes per parameter/object👇**

• invalid_settings_displayed_attributes [NEW]
• invalid_settings_searchable_attributes [NEW]
• invalid_filter -> invalid_settings_filterable_attributes [RENAME]
• invalid_sort ->invalid_settings_sortable_attributes [RENAME]
• invalid_settings_ranking_rules [NEW]
• invalid_settings_stop_words [NEW]
• invalid_settings_synonyms [NEW]
• invalid_settings_distinct_attribute [NEW]
• invalid_settings_typo_tolerance [NEW]
  • invalid_typo_tolerance_min_word_size_for_typos (Merged with invalid_settings_typo_tolerance as a message variant☝️)
• invalid_settings_faceting [NEW]
• invalid_settings_pagination [NEW]

Task API ✅

GET /tasks, POST /tasks/cancel, DELETE /tasks (Filters)

• invalid_task_date_filter ✅
  • invalid_task_before_enqueued_at [NEW]
  • invalid_task_after_enqueued_at [NEW]
  • invalid_task_before_started_at [NEW]
  • invalid_task_after_started_at [NEW]
  • invalid_task_before_finished_at [NEW]
  • invalid_task_after_finished_at [NEW]
• invalid_task_uids_filter -> invalid_task_uids ✅ [RENAME]
• invalid_task_types_filter -> invalid_task_types ✅ [RENAME]
• invalid_task_statuses_filter -> invalid_task_statuses ✅ [RENAME]
• invalid_task_canceled_by_filter -> invalid_task_canceled_by ✅ [RENAME]
• invalid_task_index_uids ✅ [NEW]
• limit parameter bad_request→ invalid_task_limit ✅ [NEW] (Only for GET)
• from parameter bad_request→ invalid_task_from ✅ [NEW] (Only for GET)

Keys API

POST /keys

• missing_parameter ✅
  • missing_api_key_actions ✅ [NEW]
  • missing_api_key_indexes ✅ [NEW]
  • missing_api_key_expires_at ✅ [NEW]

PATCH /keys/:key_or_uid

• immutable_field ✅
  • immutable_api_Key_uid ✅ [NEW]
  • immutable_api_key_actions ✅ [NEW]
  • immutable_api_key_indexes ✅ [NEW]
  • immutable_api_key_expires_at ✅ [NEW]
  • immutable_api_key_created_at ✅ [NEW]
  • immutable_api_key_update_at ✅ [NEW]

GET /keys

• limit parameter bad_request → invalid_api_key_limit ✅ [NEW]
• offset parameter bad_request → invalid_api_key_offset ✅ [NEW]

Stats API

GET /indexes/:indexUid/stats

• Sending an invalid index uid in the :indexUid path parameter returns an invalid_index_uid ✅

Misc

• invalid_geo_field → invalid_document_geo_field ✅ [RENAME]
• dump_not_found (Catch-up) [REMOVED]

type property

system ✅ [NEW]

• Moved no_space_left_on_device from internal to system ✅ [UPDATED]
• Add io_error error code ✅ [NEW]
• Add too_many_open_files error code ✅ [NEW]

internal

• Remove index_not_accessible [REMOVED]

Out Of Scope

n/a

---

Attention To Reviewers

I hope to have captured all the changes that can be made to the generic errors; please pay special attention to ensure we don't miss any.

Please do not review the message field. We will do a DX pass in the future. Changing the message field content is not considered breaking.

The OpenAPI spec never had full compliance with all our error codes; it will be added in another PR in the future.

---

Misc

• [] Update OpenAPI specification file (if needed; Apply the OpenApi label) n/a
• [] Update telemetry datapoints (if needed; Apply the Telemetry label) n/a

[gmourier]

Sharing comments with you @irevoire (Also signaling to @Kerollmops and @curquiza for an update)

I've used //TODO marker in the spec for now for the following reasons:

1. Marking message field of the newly introduced error codes (We should re-use the previous message when it was a bad_request and generated by serde to move fast, I think)
2. I've marked the 2 asynchronous errors that we wanted to make synchronous initially

[brunoocasali]

Hi @gmourier I read the spec and suggested some changes. Feel free to ignore them if you want to!

[bidoubiwa]

The following codes seem to be removed based on the spec; my bad if some are not.
The ones that are ✅, are mentioned in the body of this PR.

• ✅ invalid_geo_field
• ✅ invalid_filter
• ✅ invalid_sort
• ✅ invalid_task_uids_filter
• ✅ invalid_task_statuses_filter
• ✅ invalid_task_types_filter
• ✅ invalid_task_canceled_by_filter
• ✅ invalid_task_date_filter
• ✅ missing_parameter
• ✅ immutable_field
• api_key_already_exists
• invalid_api_key_uid
• invalid_api_key_name
• invalid_api_key_description
• invalid_api_key_actions
• invalid_api_key_indexes
• invalid_api_key_expires_at
• ✅ invalid_typo_tolerance_min_word_size_for_typos
• index_already_exists
• `index_primary_key_already_exists
• invalid_index_uid
• primary_key_inference_failed
• missing_document_id
• invalid_document_id
• invalid_ranking_rule
• ✅invalid_geo_field
• ✅ duplicate_index_found
• ✅ dump_not_found
• task_not_found
• invalid_store_file

Questions:

• is bad_request still a possible code?

[irevoire]

is bad_request still a possible code?

Yes, every time we can’t link the error to a specific field.
e.g. A syntax error happened, you provided an unknown field, maybe more? 🤔