In Contentful you model relationships between different pieces of content using something called references. The concept is very much like most any other CMS I've worked with, and suffers from the same problems. Lets say you create entry "Bob" of type Person, Bob references a profession "Developer" of type Profession. Now lets say you delete (or just unpublish) the entry "Developer". You''ll be presented with a warning in the Contentful UI:

unpublish warning

This is good, but if you ignore the warning and unpublish the entry anyway you'll end up in a state where Bob suddenly references an entry that doesn't exist, at least as far as the Content Delivery API knows. This might, of course, straight up break your app and is a scenario that you need to handle when building an application with any CMS (don't trust the editors to always behave they way you expect), but what actually happens in the Contentful API response?

{
  "sys": {
    "type": "Array"
  },
  "total": 1,
  "skip": 0,
  "limit": 100,
  "items": [
    {
      "sys": {
        "space": {
          "sys": {
            "type": "Link",
            "linkType": "Space",
            "id": "SpaceId"
          }
        },
        "id": "Bob",
        "type": "Entry",
        "createdAt": "2016-11-15T07:35:13.166Z",
        "updatedAt": "2016-11-15T08:42:59.137Z",
        "revision": 3,
        "contentType": {
          "sys": {
            "type": "Link",
            "linkType": "ContentType",
            "id": "Person"
          }
        },
        "locale": "en-US"
      },
      "fields": {
        "name": "Bob",
        "profession": [
          {
            "sys": {
              "type": "Link",
              "linkType": "Entry",
              "id": "Developer"
            }
          }
        ]
      }
    }
  ],
  "errors": [
    {
      "sys": {
        "id": "notResolvable",
        "type": "error"
      },
      "details": {
        "type": "Link",
        "linkType": "Entry",
        "id": "Developer"
      }
    }
  ],
  "includes": {
    "Entry": [
    ],
    "Asset": [
    ]
  }
}

Notice how "Bob" still contain the reference to "Developer" in the field "profession", but the referenced entry is not included in the includes.Entry array. Instead a new array is introduced errors. This is a little known and not very well documented part of the API response that is completely omitted if there are no unresolveable entities. Both unresolved entries and assets end up in this array. This gives you as a developer a chance to programmatically verify if a reference is unresolved and most likely unpublished or deleted and take some appropriate measure. In the Contentful .NET SDK every call that returns a ContentfulCollection automatically includes the errors array if present.

error array

The Errors property of the ContentfulCollection is an IEnumerable<ContentfulError> that includes all the details of the api response above. The actual reference property in the entry model will be null. For example if you had a Person class with a reference property to a Profession, something like this:

public class Person {
  public string Name { get; set; }
  public Profession Profession { get; set; }
}

The Profession property would be null, but the missing reference would be included in the Errors property.

I've seen some confusion in the past about how unresolveable entities are handled in Contentful, but I hope this small post cleared it up a bit. Let me know what you think.