This page explains when to run your write calls (Section 1.1), describes potential maintenance windows (Section 1.2), lists references to changes and the server status (Section 2), and provides an overview of possible errors while writing, their causes and solutions (Section 3.1). Additionally, it lists errors that can appear while reading data, describes potential causes and proposes solutions.

1. Import Timing & Maintainance Windows

Please notice the following time frames.

1.1 Imports: 10 pm to 4 am

Please do not start your regular imports before 10 pm or after 4 am (CEST time). Small data badges for development, testing, or hotfix purposes can be imported at any time but might run into issues in the maintenance window (see below).

1.2 Maintainance Window: 8 pm to 10 pm

The timeframe between 8 and 10 pm is reserved for server maintenance and database backups. During this time, you might encounter issues with write operations. Read operations are not affected at any time.

2. Helpful Resources

This section references resources that support the debugging process in case API calls fail.

2.1 Changelog

Whenever the API or the Meta description of the data (the Domain Specifications) changes, the differences will be described on the Changelog Blog.

An RSS changelog version is also available: https://changelog-dzt-kg.readme.io/changelog.rss to which you can subscribe.

2.2 Status Page

The status of the environment (including the platform, the API, the Graph database and other databases) is monitored here: https://status.opendatagermany.io/

This page contains the system's current status, lists historical incidents and allows for a subscription. Besides subscription options for Email and Slack, there is also an option for RSS: https://status.opendatagermany.io/statuspage/onlim-status-dzt-production/subscribe/rss

3. Common errors...

...causes and solutions

3.1 Error messages while importing

3.1.1 Duplicate Entity Error: Import Conflict

Error message: Your current import contains entities with @ids that are also present in a previous import that is still being processed. Please retry once the previous import is complete.

fka: One or more documents in payload are still processing state, can not accept other imports on same document, please retry once the processing for the documents has finished!

Cause: The issue arises because the current import batch contains entities identified by @ids that are duplicates of entities present in a previous import batch, which is currently undergoing processing.

Solution 1: Retry the import once the processing of the previous batch, which contains duplicate @ids, has been completed.

Solution 2: Don't send the same entity twice within a short period.

Counterexample: Two entities referring to the same nested entity imported right after each other would NOT cause the error.

Import 1:

{
  "@context": "https://schema.org",
  "@type": "Event",
  "@id": "https://example.com/event/12345",
  "name": "Sample Event ONE",
  "startDate": "2024-07-21T19:00:00Z",
  "endDate": "2024-07-21T21:00:00Z",
  "location": {
    "@type": "Place",
    "@id": "https://example.com/venue/xxxxx",
    "name": "Event Venue"
  },
  "description": "This is a sample event description.",
  "image": "https://example.com/event/image.jpg"
}

Import 2:

{
  "@context": "https://schema.org",
  "@type": "Event",
  "@id": "https://example.com/event/54321",
  "name": "Sample Event TWO",
  "startDate": "2024-07-21T19:00:00Z",
  "endDate": "2024-07-21T21:00:00Z",
  "location": {
    "@type": "Place",
    "@id": "https://example.com/venue/xxxxx",
    "name": "Event Venue"
  },
  "description": "This is a sample event description.",
  "image": "https://example.com/event/image.jpg"
}

This is technically not an error, but it writes the same information twice. If import 2 starts before import 1 finishes, the error is thrown.

To solve that, restructure your import, for example, like this:

Import 1:

{
  "@context": "https://schema.org",
  "@type": "Place",
  "@id": "https://example.com/venue/xxxxx",
  "name": "Event Venue"
}

Import 2:

{
  "@context": "https://schema.org",
  "@type": "Event",
  "@id": "https://example.com/event/12345",
  "name": "Sample Event ONE",
  "startDate": "2024-07-21T19:00:00Z",
  "endDate": "2024-07-21T21:00:00Z",
  "location": {
    "@id": "https://example.com/venue/xxxxx"
  },
  "description": "This is a sample event description.",
  "image": "https://example.com/event/image.jpg"
}

Import 3:

{
  "@context": "https://schema.org",
  "@type": "Event",
  "@id": "https://example.com/event/54321",
  "name": "Sample Event TWO",
  "startDate": "2024-07-21T19:00:00Z",
  "endDate": "2024-07-21T21:00:00Z",
  "location": {
    "@id": "https://example.com/venue/xxxxx"
  },
  "description": "This is a sample event description.",
  "image": "https://example.com/event/image.jpg"
}

3.1.2 Graph write failed

Error message: Write to the graph database failed: ...

fka: Write to storage failed: ...

Cause: The ellipsis (...) in the error message gives more information about why a given call failed. Most likely, it was due to a temporary issue, which could be correlated with the incident log mentioned in 2.2 or an ongoing maintenance mentioned in 1.2.

Solution: Retry your import a bit later and ensure the import time is not within the maintenance window mentioned in 1.2.

3.1.3 Graph write failed

Error message: An error occurred while writing the import to the graph database! Please retry the import!

fka: exception while saving import models to storage!

Solution: Retry your import a bit later and ensure the import time is not within the maintenance window mentioned in 1.2.

3.2 Error messages in import reports

3.2.1 More than one graph

Error message: The data you are trying to update is in more than one graph!

fka: update data is in more that one graph!

Cause: It is not allowed to update data in different graphs in one import process.

Solution: Split the data so that you write to only one graph at a time. Make sure that you use the right credentials to access the respective graph.

3.2.2 Already existing entity

Error message: The creation was aborted because the entity you are trying to write already exists!

fka: abort create, KG Thing ... exists already!

Cause: You can not overwrite entities with a create method!

Solution: Use the UPSERT Endpoint: https://changelog-dzt-kg.readme.io/docs/upsert-of-objects!