Error Handling

The Translation Management API provides robust error handling to ensure data integrity and developer clarity. This section describes how errors are validated, how partial successes are managed, and provides examples of error responses.

Error Validation Types

Translation Management API performs two types of validation on requests:

Resource ID/Type Validation:
Ensures that the specified resource (e.g., Category, Brand, Product) exists and is valid. If an incorrect or non-existent resource ID or type is provided, an error is returned.
- EntityNotFoundError:
  Returned when the specified resource does not exist.
  Example: "message": "Entity bc/store/category/28 not found."
- ValidationError:
  Returned when the query fails validation rules. This can include incorrect resourceType, mismatched resourceType and resourceId, as well as missing fields.
  Example: "message": "Invalid value for resourceType"
  Example: "message": "resourceId must be an integer for resourceType PRODUCTS."
Field Name Validation:
Ensures that the field names submitted in the translation request are valid for the specified resource type. Invalid or unsupported field names result in error responses.
- InvalidTranslationEntityFieldsError:
  Returned when one or more field names are not valid for the specified resource type.
  The response includes the invalid field names in the fields array.
  Example: "fields": ["invalidField1", "invalidField2"]

Partial Success

The API supports partial success in mutation operations. If only some of the translated entities (resources or fields) are valid, the API will update those and return errors for the invalid ones. This allows you to identify and correct issues without losing valid updates.

Example: Error Response

Below is an example demonstrating how the API responds to a request containing both invalid resource IDs and invalid field names.

Mutation

Response

Example Mutation

The following example demonstrates a mutation call to the Translation Management API where the request includes both invalid resource IDs and invalid field names. This is useful for testing how the API handles multiple types of validation errors in a single request. The mutation attempts to update translations for a category resource, but includes two invalid field names (invalidField1 and invalidField2) among otherwise valid fields.

GRAPHQL {{host}}/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
mutation {
  translation {
    updateTranslations(input: {
      resourceType: CATEGORIES,
      channelId: "bc/store/channel/{{channel_id}}",
      localeId: "bc/store/locale/it",
      entities: [
        {
          resourceId: "bc/store/category/28",
          fields: [
            {
              fieldName: "invalidField1",
              value: "Comprar todo 2"
            },
            {
              fieldName: "invalidField2",
              value: "Comprar todo 2"
            },
            {
              fieldName: "page_title",
              value: "Comprar todo 2"
            },
            {
              fieldName: "meta_description",
              value: "Comprar todo 2"
            },
            {
              fieldName: "search_keywords",
              value: "Comprar todo"
            }
          ]
        }
      ]
    }) {
      errors {
        __typename
        ... on InvalidTranslationEntityFieldsError {
          message
          fields
        }
      }
      errors {
        __typename
        ... on EntityNotFoundError {
          message
        }
      }
    }
  }
}