Error handling

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.

HTTP Status Codes

The ContentGrid Application API uses standard HTTP status codes to indicate the success or failure of API requests.

These status codes provide high-level information about what happened with your request, and are generically described in RFC9110.

Successful Responses (2xx)

  • 200 OK: The request succeeded. The response body contains the requested resource or data.
  • 201 Created: A new resource was successfully created. The Location header contains the URL of the newly created resource.
  • 204 No Content: The request succeeded but there is no response body. This is typically returned after successful updates or deletions.

Redirection Responses (3xx)

  • 302 Found: The resource is temporarily available at a different URI. The Location header contains the URI where the resource can be found. This is commonly used when accessing relations.

Client Error Responses (4xx)

  • 400 Bad Request: The request is malformed or contains invalid data. The response body may contain a problem detail explaining what went wrong if the request is sufficiently syntactically valid to be able to be processed.
  • 401 Unauthorized: The request lacks valid authentication credentials.
  • 403 Forbidden: The server understood the request but refuses to authorize it. This occurs when you don’t have permission to perform the requested operation.
  • 404 Not Found: The requested resource does not exist. This could be an entity that doesn’t exist, an empty relation, or an unknown endpoint.
  • 409 Conflict: The request conflicts with the current state of the resource. This occurs with unique constraint violations or when trying to delete an entity that is still referenced by required relations.
  • 412 Precondition Failed: The condition specified in the request headers (If-Match or If-None-Match) was not met. This typically occurs when using optimistic locking and the entity has been modified by another request.
  • 415 Unsupported Media Type: The Content-Type header specifies a media type that the server doesn’t support for this endpoint.

Server Error Responses (5xx)

  • 500 Internal Server Error: An unexpected error occurred on the server. Contact support if this persists.

Problem Details (RFC 9457)

When an error occurs (4xx or 5xx status codes), the API returns a standardized error response using the RFC9457 Problem Details format. This provides a consistent, machine-readable way to communicate error information.

Problem Detail Structure

All error responses have Content-Type: application/problem+json and include these standard fields:

  • type (string): A URI identifying the problem type (e.g., https://contentgrid.cloud/problems/not-found/entity-item)
  • title (string): A short, human-readable summary of the problem type
  • detail (string): A human-readable explanation specific to this occurrence of the problem
  • status (number): The HTTP status code for this problem
  • Additional properties: Problem-specific fields that provide more context
Example
​
curl -i -X PATCH https://$APP_ID.$REGION.contentgrid.cloud/invoices/$INVOICE_ID   \
    --json "{\"pay_before\": \"2024-08-13\"}"   \
    -H 'If-Match: "outdated-version"'   \
    -H "Authorization: Bearer $TOKEN"

PATCH /invoices/$INVOICE_ID HTTP/1.1
Authorization: Bearer $TOKEN
If-Match: "outdated-version"
Content-Type: application/json

{"pay_before": "2024-08-13"}
HTTP/1.1 412 Precondition Failed
Content-Type: application/problem+json

{
  "type": "https://contentgrid.cloud/problems/unsatisfied-version",
  "title": "Object has changed",
  "detail": "Requested version constraint 'is any of [exactly 'outdated-version']' can not be satisfied (actual version exactly '1r061qt')",
  "status": 412,
  "actual_version": "1r061qt"
}

Problem Types Reference

For a complete catalog of all problem types returned by the ContentGrid API, see the Problem Types reference.