Hanami Exceptions

Common Error Response Fields

Every error response follows a standard structure to maintain consistency and ease of understanding. Below are the fields that are included in each error response:

• id: A unique identifier for the error instance. Useful for support and debugging purposes.
• status: The HTTP status code applicable to this problem, expressed as a string value.
• code: A short, human-readable summary of the problem type. It should not change from occurrence to occurrence of the problem, unless the semantics also change.
• meta: A meta object containing non-standard meta-information about the error.

Error Response Format Example

{
  "errors": [
    {
      "id": "unique-error-identifier",
      "status": "specific-http-status-code",
      "code": "error-code",
      "meta": {
        // ... additional details specific to the error ...
      }
    }
    // ... other errors ...
  ]
}

Uri generator exceptions

UriGenerator_UriInternalOverlap Error

HTTP Status: 400 Bad Request

This error indicates a conflict where a newly generated URI already exists within the current graph.

• Cause
  • The error is usually due to misconfiguration in the URI generation process that does not properly check for existing URIs.
• Resolution
  • Check and correct the URI generation configuration to ensure it verifies the uniqueness of URIs before assigning them.
  • Make sure the values entered result in a unique URI
• Metadata
  • The response will contain a meta field with a list of overlapping URIs.
  Example:

  "meta" : {
    "overlappingUris": ["https://example.com/uri-that-already-exists"]
  }
• Response Example

  {
    "errors": [
      {
        "id": "335ad47b-0a7e-4934-940d-41103ae4ec15",
        "status": "400",
        "code": "UriGenerator_UriInternalOverlap",
        "meta": {
          "meta": {
            "overlappingUris": [
              "https://fedlex.data.admin.ch/fga/compendium/2021-9/2"
            ]
          }
        }
      }
    ]
  }

UriGenerator_UriExternalOverlap Error

HTTP Status: 400 Bad Request

This error indicates a conflict where a newly generated URI already exists within another graph in the triple store

• Cause

  • The error is usually due to misconfiguration in the URI generation process that does not properly check for existing URIs.

• Resolution

  • Check and correct the URI generation configuration to ensure it verifies the uniqueness of URIs before assigning them.
  • Make sure the values entered result in a unique URI

• Metadata

  • The response will contain a meta field with a list of overlapping URIs and in which graph they appear.

  Example:

        "meta": {
          "overlappingUris": [
            {
              "itemUri": "https://example.com/uri-that-already-exists",
              "graphUri": "https://example.com/graph-that-already-exists"
            },
            ...
          ]
        }

• Response Example

  {
    "errors": [
      {
        "id": "ff30c18c-b556-4846-b475-005d3ef65bc1",
        "status": "400",
        "code": "UriGenerator_UriExternalOverlap",
        "meta": {
          "meta": {
            "overlappingUris": [
              {
                "graphUri": "https://fedlex.data.admin.ch/fga/compendium/2021-9/2/graph",
                "itemUri": "https://fedlex.data.admin.ch/fga/compendium/2021-9/2"
              }
            ]
          }
        }
      }
    ]
  }

UriGenerator_InternalError Error

HTTP Status: 500 Internal Server Error

• Cause
  • The error is thrown when something unexpectedly went wrong while generating the new URIs
• Resolution
  • Resolution depends on the error message. Contact support when it is unclear how to resolve the issue
• Details
  • The response will contain an error message explaining what went wrong

Response Example

{
  "errors": [
    {
      "id": "fd4bab09-1dcf-4c6d-ab52-65318088e526",
      "status": "500",
      "code": "UriGenerator_InternalError",
      "details": "Query failed: {query that failed} with error "
    }
  ]
}

UriGenerator_DuplicateVariables Error

HTTP Status: 500 Internal Server Error

This error indicates a variable is selected twice by different selectors for URI generation

• Cause

  • The error is usually due to misconfiguration in the URI generation where different variable selector queries select the same variable

• Resolution

  • Check the variable selectors and make sure they don't select the same variable

• Metadata

  • The response will contain a meta field with a generatorId and the duplicated variables it selected

  Example:

    {
      "meta": {
         "generator": "generatorId",
         "duplicateVariables": ["duplicatedVariable", "var2"]
      }
    }

Response Example

{
    "errors": [
        {
            "id": "4386b208-7686-4535-812c-2003899a9cb6",
            "status": "500",
            "code": "UriGenerator_DuplicateVariables",
            "meta": {
                "meta": {
                    "generatorId": "Expression",
                    "duplicateVariables": [
                        "parent"
                    ]
                }
            }
        }
    ]
}

UriGenerator_MissingVariables Error

HTTP Status: 400 Bad Request

This error indicates a variable needed for URI generation was not bound

• Cause

  • The error is usually due to a required property that is missing

• Resolution

  • Make sure to enter a value for every required property

• Metadata

  • The response will contain a meta field with the missing variables

  Example:

    {
      "meta": {
         "missingVariables": ["missingVariable1", "missingVariable2"]
      }
    }

Response Example

{
  "errors": [
    {
      "id": "b377da54-562c-4520-8c48-078ed6267bf9",
      "status": "400",
      "code": "UriGenerator_MissingVariables",
      "meta": {
        "meta": {
          "missingVariables": [
            "parent",
            "languageCode"
          ]
        }
      }
    }
  ]
}

UriGenerator_MultipleResults Error

HTTP Status: 500 Internal Server Error

This error indicates a variable select query returned multiple results

• Cause

  • The error is usually due to a property having multiple values even though it should only have one value
  • This error might also be due to a misconfiguration in the URI generator, where a select query returns multiple results

• Resolution

  • Make sure properties used for URI generation have exactly 1 value
  • Rewrite select query to only have one result

• Metadata

  • The response will contain a meta field with a generatorId and the rows being returned by the problematic query

  Example:

    {
    "meta": {
        "generator": "generatorId",
        "rows":  [
                  {
                      "var1": "https://example.com/uri/1",
                      "var2": "literal1"
                  },
                  {
                      "var1": "https://example.com/uri/2",
                      "var2": "literal2"
                  }
            ]
      }
    }

Response Example

{
  "errors": [
    {
      "id": "01015096-03f4-426f-9a49-8690f8835da5",
      "status": "500",
      "code": "UriGenerator_MultipleResults",
      "meta": {
        "meta": {
          "generator": "Expression",
          "rows": [
            {
              "parent": "https://fedlex.data.admin.ch/fga/compendium/2021-9/2",
              "languageCode": "fr"
            },
            {
              "parent": "https://fedlex.data.admin.ch/fga/compendium/2021-9/2",
              "languageCode": "en"
            }
          ]
        }
      }
    }
  ]
}

Indexing exceptions

Index_InternalError

• description: an error occurred while indexing
• status code: 500
• details: A message (in English) describing what went wrong
• meta: null

Example [TBA]

Item CRUD exceptions

Load_UriOverlap

• description: a file was loaded that generates a graph URI that already exists
• status code: 409
• details: null
• meta:

  • {
    graphUri: {graphUri}
    }
  • {graphUri}: the graph uri generated from the uploaded data

Example

{
    "errors": [
        {
            "id": "8d6bae59-8dbe-496d-829e-fa01779561ec",
            "status": "409",
            "code": "Load_UriOverlap",
            "meta": {
                "graphUri": "http://publications.europa.eu/resource/authority/browser/graph"
            }
        }
    ]
}

Update_RootDelete

• description: the root node that generates the graph uri was deleted
• status code: 400
• details: Model to update does not contain the root that generated the graph uri {root node uri}
• meta: null

Example [TBA]

Copy_InternalReferences

• description: user tries to copy nodes that contains internal references. An internal reference is a node that has a triple of which the predicate is not rdf:type, except for the node that is being copied.
• status code: 400
• details: null
• meta:

  • { 
    internalReferences: {[nodeUris]}
    }
  • {[nodeUris]}: a list of URIs that are internal references

Example

{
    "errors": [
        {
            "id": "6e7df5d0-82ff-4e22-98c9-1bdb2882abe7",
            "status": "400",
            "code": "Copy_InternalReferences",
            "meta": {
                "internalReferences": [
                    "https://fedlex.data.admin.ch/eli/cc/2008/499/maintext_/fr",
                    "https://fedlex.data.admin.ch/eli/cc/2008/499/maintext_/20080701",
                    "https://fedlex.data.admin.ch/eli/cc/2008/499/maintext_/20080701/de",
                    "https://fedlex.data.admin.ch/eli/cc/2008/499/maintext_/20080701/fr",
                    "https://fedlex.data.admin.ch/eli/cc/2008/499/maintext_/20080701/it",
                    "https://fedlex.data.admin.ch/eli/cc/2008/499/maintext_/de",
                    "https://fedlex.data.admin.ch/eli/cc/2008/499/maintext_/it"
                ]
            }
        }
    ]
}

Actions exceptions

Actions_FailOnCondition

• description: thrown by an ActionsOnFailStep
• status code: 400
• details: {message}
  • {message}: the configured message to throw when fail condition is met
• meta: null

Example

{
    "errors": [
        {
            "id": "a266b6e5-d579-4b94-89f1-1710d34ea3f3",
            "status": "400",
            "code": "Actions_FailOnCondition",
            "details": "Cannot save because no french tag was given"
        }
    ]
}