Problem Types

The ContentGrid REST API uses the standard HTTP status codes to signal errors.

RFC9457 Problem Details are used to provide additional information about the error condition.

This reference describes all Problem Detail types that can be returned by the ContentGrid Application REST API.

Unless specified otherwise, the HTTP Status code for problems will be 400 Bad Request.

Input Validation Problems

These problems occur when the data you provide in the request body doesn’t meet the requirements.

Input validation problems are always represented by the a Problem Detail with type https://contentgrid.cloud/problems/input/validation.

input/validation

https://contentgrid.cloud/problems/input/validation

The ProblemDetail contains an additional property, errors, which contains a list of validation errors.

Each validation error has the same structure as a ProblemDetail, with as type one of the subtypes listed below. Each validation error also has a field property, which refers to the specific input field for which validation failed with a property path.

Example 
{
  "type": "https://contentgrid.cloud/problems/input/validation",
  "title": "Validation error",
  "detail": "2 validation errors",
  "status": 400,
  "errors": [
    {
      "type": "https://contentgrid.cloud/problems/input/validation/required",
      "title": "Mandatory field",
      "detail": "A value must be present, but it is missing or empty",
      "field": "pay_before"
    },
    {
      "type": "https://contentgrid.cloud/problems/input/validation/type",
      "title": "Invalid data type",
      "detail": "Expected value of type date, but got decimal",
      "field": "received",
      "expected_type": "date",
      "actual_type": "decimal"
    }
  ]
}

input/validation/type

https://contentgrid.cloud/problems/input/validation/type

The value provided has the wrong data type.

A data type error can happen when handling a JSON or a multipart form body.

For example:

  • sending a decimal instead of a long
  • sending a JSON array instead of a single value
  • sending a JSON object instead of a single value
  • repeating the same multipart form field multiple times instead of once
  • sending a multipart file instead of a normal form field

Additional Properties:

  • expected_type (string): The technical name of the expected data type
  • actual_type (string): The technical name of the actual data type received

input/validation/type/format

https://contentgrid.cloud/problems/input/validation/type/format

The value is of the correct type, but it doesn’t match the expected format.

In this case the type is correct (usually a string), but the type (e.g. date, timestamp, relation link) requires a specific format, which was not fulfilled.

For example:

  • sending an arbitrary string instead of a date or timestamp in RFC3339 format
  • sending a link to an entity that is of the wrong type for this relation

Additional Properties:

  • expected_type (string): The expected data type
  • format_error (string): Description of the format error

input/validation/no-content

https://contentgrid.cloud/problems/input/validation/no-content

A content attribute can not be set when there is no content present.

This happens when writing to nested fields in a content attribute, but there is no content present.

It is only valid to change content fields (e.g. set filename or mimetype) when an actual file is present.

input/validation/required

https://contentgrid.cloud/problems/input/validation/required

A required field is set to null.

Note

When using PUT to update an entity, all attributes that are not present in the request body are regarded to be null (including attributes of type content). Use the PATCH method if you only want to update some fields.

input/validation/duplicate

https://contentgrid.cloud/problems/input/validation/duplicate

The value provided for an attribute must be unique, but an other entity item already uses this value.

Additional Properties:

  • conflicting_item (string): URL of the entity that already has this value

input/validation/allowed-values

https://contentgrid.cloud/problems/input/validation/allowed-values

The value is not one of the allowed values.

The possible values for an attribute can be restricted to a list of allowed values. It is then not allowed to use any other value.

Additional Properties:

  • allowed_values (list): A list of all the values that are allowed for the field

Query Parameter Problems

These problems occur when request query parameters don’t meet the requirements.

Contrary to input validation, only a single problem is reported at a time.

invalid-query-parameter/filter/format

https://contentgrid.cloud/problems/invalid-query-parameter/filter/format

Query parameter values are always strings. For some operations, they need to be converted to a certain type (e.g. to a number for a greater-than filter, or to a timestamp for a before filter).

If the value can not be converted, this problem is reported

Additional Properties:

  • query_parameter (string): The name of the query parameter
  • attribute (string): The name of the attribute that is being searched on
  • expected_type (string): The expected data type
  • format_error (string): Description of the format error

invalid-query-parameter/sort/format

https://contentgrid.cloud/problems/invalid-query-parameter/sort/format

The _sort query parameter is malformed and doesn’t match the expected format.

The expected format for sorting is <attribute_name>,asc or <attribute_name>,desc for ascending and descending sorting. Other formats are invalid.

Additional Properties:

  • query_parameter (string): The name of the query parameter (always _sort)

invalid-query-parameter/sort/attribute

https://contentgrid.cloud/problems/invalid-query-parameter/sort/attribute

The _sort query parameter references an attribute that doesn’t exist, or on which sorting is not possible.

Sorting is only possible on attributes that are indexed in a way that supports sorting.

Additional Properties:

  • query_parameter (string): The name of the query parameter (always _sort)
  • attribute (string): The attribute which couldn’t be sorted on

invalid-query-parameter/pagination

https://contentgrid.cloud/problems/invalid-query-parameter/pagination

A pagination-related query parameter (_cursor or _limit) is invalid.

  • The _limit field value must be 1-1000.
  • The _cursor field value should never be manually constructed; use the next_cursor and prev_cursor values from API responses (or follow the HAL links).

Additional Properties:

  • query_parameter (string): The name of the query parameter

General request problems

These problems occur when there is something wrong with the request in general, in ways that are normally never encountered when integrating with ContentGrid.

They are still listed here for reference.

invalid-request/body/json

https://contentgrid.cloud/problems/invalid-request/body/json

The request body contains malformed JSON that can not be parsed.

https://contentgrid.cloud/problems/invalid-request/body/single-link

The request body does not have exactly one link.

This problem occurs when sending a request containing multiple (or zero) links to a to-one relation. A PUT on a to-one relation must contain exactly one link.

invalid-request/required-header

https://contentgrid.cloud/problems/invalid-request/required-header

A required HTTP header is missing from the request.

Additional Properties:

  • header (string): The name of the header that is missing

invalid-request/forbidden-header

https://contentgrid.cloud/problems/invalid-request/forbidden-header

A HTTP Header is present that is not allowed

Additional Properties:

  • header (string): The name of the header that is not allowed

invalid-request/invalid-header

https://contentgrid.cloud/problems/invalid-request/invalid-header

A HTTP Header has a value that is not syntatically valid

Additional Properties:

  • header (string): The name of the header that is not valid

Version Conflict Problems

unsatisfied-version

https://contentgrid.cloud/problems/unsatisfied-version

The entity version specified in the If-Match and/or If-None-Match headers doesn’t match the current version.

This error can happen when using conditional requests, and the entity is modified by another request between get and update.

HTTP Status: 412 Precondition Failed

Additional Properties:

  • actual_version (string): The current version of the entity

Not Found Problems

These problems have HTTP status code 404 Not Found.

Different problem types are used to help distinguish between typos in URLs and entity items that may not be present anymore.

not-found/endpoint

https://contentgrid.cloud/problems/not-found/endpoint

The requested API endpoint does not exist.

This problem type indicates an error in the fixed parts of the URL: in the entity, relation or attribute name.

Check the URL for typos. Ensure you’re using the correct entity type name and that the entity type exists in your data model. If the URL used to work, check that the entity/attribute/relation definition was not renamed or deleted in a newer version of the data model.

not-found/entity-item

https://contentgrid.cloud/problems/not-found/entity-item

No entity was found with the specified id. The entity may have been deleted, or may have never existed.

not-found/relation-item

https://contentgrid.cloud/problems/not-found/relation-item

The relation does not contain the requested entity-item.

This can happen for all relation types:

  • to-one relations: When nothing is linked, a GET or DELETE on the relation resource will result in this error
  • to-many relations: When a specific item is not linked, a GET or DELETE on the relation-item resource will result in this error

Integrity Problems

These problems occur when an operation would violate data integrity constraints.

Unless specified otherwise, integrity problems will use the 409 Conflict HTTP status code.

integrity/invalid-relation-target

https://contentgrid.cloud/problems/integrity/invalid-relation-target

One or more entity-items that are being linked don’t exist.

HTTP Status: 400 Bad Request

Additional Properties:

  • errors (array): List of target errors, each containing details about a missing target (of type not-found/entity-item)

integrity/blind-relation-overwrite

https://contentgrid.cloud/problems/integrity/blind-relation-overwrite

In a to-one relation, the target entity is already referenced by another entity. The operation would silently overwrite that reference without ability to apply proper concurrency control.

Additional Properties:

  • new_item (string): URL of the entity you’re trying to link
  • new_relation (string): URL of the relation you’re trying to set
  • existing_item (string): URL of the entity currently linked
  • existing_relation (string): URL of the existing relation
  • target_item (string): URL of the target entity
  • target_relation (string): URL of the inverse relation (if available)

How to Fix: This is a safety mechanism to prevent data loss. You have several options:

  1. Unlink the existing relation first (DELETE on existing_relation), then create the new link
  2. Use the target entity’s relation endpoint to manage the link, if available
  3. Review your data model - you may need a to-many relation instead of to-one

integrity/required-relation

https://contentgrid.cloud/problems/integrity/required-relation

This problem indicates that the entity-item is referenced in a required relation

It can happen when:

  1. trying to delete the entity-item, and it is referenced by any required relation
  2. trying to unlink the entity-item from a relation, and the other side of the relation is required.

HTTP Status: 409 Conflict

Additional Properties:

  • affected_relation (string): URL of the relation that requires this entity

How to Fix: Before deleting or unlinking the entity, either:

  1. Delete the referencing entity first
  2. Update the referencing entity to link to a different entity
  3. If the relation should be optional in your data model, update your model definition