Content Delivery API > Error codes & handling failures (CDA)

Content Delivery API Errors and Failure Modes

CDA errors happen when your frontend fails to query our GraphQL Content Delivery API for any reason.

This can occur at different parts of the network stack, with different kinds of errors and responses, detailed below.

Table of CDA Error Types & Failure Modes

Network Errors

Network errors occur when your request never made it to our servers. This can be due to a Wi-Fi problem, misconfigured VPN, corporate firewall, regional network outage, browser or HTTPS issue, etc. Rarely, it might also indicate server outages and downtime on our part. You can always check out status page at https://status.datocms.com/ or the Outages section of the DatoCMS forum.

GraphQL Query Errors

GraphQL query errors occur when the request reached our GraphQL server OK, but there was something wrong with the query itself.

A successful CDA response looks like:

1
// Successful CDA responses will have a data[] array and no errors[] array.
2
// It will have a HTTP 200 OK status.
3

4
{
5
  "data": {
6
    "allArticles": [
7
      {
8
        "id": "abcdefghji12345",
9
        "title": "This is an example article",
10
        "slug": "example-article"
11
      }
12
    ]
13
  }
14
}

A failed CDA response looks like:

1
// Failed CDA queries will return an errors[] array instead of data[]
2
// Failed queries will ALSO have a HTTP 200 OK status. DO NOT TRUST THAT!
3

4
{
5
  "errors": [
6
    {
7
      "message": "Field 'Sku' doesn't exist on type 'ArticleRecord'",
8
      "locations": [
9
        {
10
          "line": 16,
11
          "column": 5
12
        }
13
      ],
14
      "path": [
15
        "query",
16
        "allArticles",
17
        "Sku"
18
      ],
19
      "extensions": {
20
        "code": "undefinedField",
21
        "typeName": "ArticleRecord",
22
        "fieldName": "Sku"
23
      }
24
    }
25
  ]
26
}

Within an errors[] array, each object will have the following properties:

• message: The human-readable error message.

• locations: The query line and column # where the server thinks the error occurred. Note that because of formatting and line break differences, the precise location may be slightly different in your code.

• path: The attempted GraphQL path (e.g. query.modelName.fieldName) that caused the error.

• extensions: Extended DatoCMS-specific errors that we provide to try to help you diagnose what went wrong. May be different for different kinds of query errors.

HTTP & API Errors

HTTP & API errors occur when the network request itself has an issue. The most common examples are invalid authorization tokens or hitting the rate limit on uncached queries.

An HTTP or API error will have a shape similar to this:

{
  "id": "abcde12345",
  "type": "api_error",
  "attributes": {
    "code": "INVALID_JSON_BODY", // Machine-parseable code
    "details": {
      "message": "The JSON body you submitted is not a valid GraphQL request" // For humans
    }
  }
}

attributes.code will be the machine-readable error code. See below for a list.

attributes.details.message will be a short, human-readable explanation.

List of HTTP & API Error Codes

INVALID_AUTHORIZATION_HEADER

This error occurs when the provided API Authorization header is invalid or absent. Ensure that the API token used in the request is valid, has appropriate Content Delivery API (CDA) access permissions, and that the header is properly formatted.

INVALID_ENVIRONMENT

This error occurs when the GraphQL API request targets an environment that doesn’t exist. Check your environment identifier in the request.

INVALID_JSON_BODY

The JSON request body is itself malformed or invalid, and our server can't find your query in the request. Perhaps you missed a bracket? Please see Your first request or use the "Playground" in your project, along with your browser's network inspector, to see what a properly-formed request would look like.

ENVIRONMENT_NOT_READY

This error occurs when attempting to access an environment that exists but is not in a “ready” state. To resolve this, ensure that the environment you’re targeting has transitioned to “ready” status. You can check the current environment’s status via the DatoCMS interface or API before making modification requests.

DEACTIVATED_SITE

This error occurs when attempting to access a site that has been deactivated. To fix this, go to the DatoCMS dashboard and address any pending billing issues.

SITE_NOT_READY

This error occurs when attempting to access a site that exists but is not in a “ready” state. The site may be initializing. Verify that the desired project is accessible, activated, and ready.

INSUFFICIENT_PERMISSIONS

This error occurs when a valid API token exists but lacks the necessary permissions to access the requested environment. The authentication succeeds, but the token doesn’t have the required authorization level for the operation. Ensure your API token has the appropriate role and permission settings for the environment you’re trying to access.

INVALID_X_INCLUDE_DRAFTS_HEADER

This error occurs when the X-Include-Drafts header in your GraphQL API request has an invalid value. The header can only be set to “true” to include draft content in the response. Ensure your API request uses the correct value for this header or omit it entirely if you don’t need draft content.

INVALID_X_EXCLUDE_INVALID_HEADER

This error occurs when the X-Exclude-Invalid header in your GraphQL API request has an invalid value. The header can only be set to “true” to exclude invalid content items from the response. Verify that your request uses the correct value for this header or remove it if not needed.

INVALID_X_VISUAL_EDITING_HEADER

(Enterprise Feature)

This error occurs when the X-Visual-Editing header is provided, but your site doesn’t have visual editing capabilities, which is an enterprise-only feature. Contact support@datocms.com for information about upgrading your plan to access this functionality.

INVALID_X_VISUAL_EDITING_HEADER

(Invalid Value)

This error occurs when the X-Visual-Editing header is provided with an invalid value. Currently, the only supported value for this header is “vercel-v1”. Ensure your API request uses the correct value for this header when using visual editing features.

INVALID_X_BASE_EDITING_URL_HEADER

This error occurs when the X-Visual-Editing header is specified but the required X-Base-Editing-Url header is missing. When using visual editing features, you must provide the base editing URL to properly generate editing links. Ensure both headers are properly configured in your request.