# 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.

> [!NOTE] These errors are only for the GraphQL Content Delivery API
> If you're looking for errors related to our REST Content Management API, please instead see: [Error codes & handling failures (CMA)](https://www.datocms.com/docs/content-management-api/errors.md)

## 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/](https://status.datocms.com/) or the [Outages section of the DatoCMS forum](https://community.datocms.com/c/outages/25).

## GraphQL Query Errors

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

> [!WARNING] GraphQL query errors will still return a HTTP 200 OK
> If a malformed or otherwise invalid query reaches our GraphQL server, you'll still receive a `**200 OK**` **HTTP status.** But that doesn't mean the query succeeded, only that our server received it. **The HTTP status is NOT a way to see if a query succeeded. Instead, you must check for the possible presence of an** **`errors[]`** **array.**

A **successful** CDA response looks like:

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

{
  "data": {
    "allArticles": [
      {
        "id": "abcdefghji12345",
        "title": "This is an example article",
        "slug": "example-article"
      }
    ]
  }
}
```

A **failed** CDA response looks like:

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

{
  "errors": [
    {
      "message": "Field 'Sku' doesn't exist on type 'ArticleRecord'",
      "locations": [
        {
          "line": 16,
          "column": 5
        }
      ],
      "path": [
        "query",
        "allArticles",
        "Sku"
      ],
      "extensions": {
        "code": "undefinedField",
        "typeName": "ArticleRecord",
        "fieldName": "Sku"
      }
    }
  ]
}
```

`**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:

```json5
{
  "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 [Using the JavaScript CDA client](https://www.datocms.com/docs/content-delivery-api/your-first-request.md) 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](mailto: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 values for this header are `v1` and `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.

## Related content in "Content Delivery API"

- [Content Delivery API Overview](https://www.datocms.com/docs/content-delivery-api.md)
- [Using the JavaScript CDA client](https://www.datocms.com/docs/content-delivery-api/your-first-request.md)
- [Authentication and permissions](https://www.datocms.com/docs/content-delivery-api/authentication.md)
- [Configuring requests: envs, drafts, strict mode, cache tags, etc.](https://www.datocms.com/docs/content-delivery-api/api-endpoints.md)
- [How to fetch records](https://www.datocms.com/docs/content-delivery-api/how-to-fetch-records.md)
- [Filtering records](https://www.datocms.com/docs/content-delivery-api/filtering-records.md)
- [Deep Filtering](https://www.datocms.com/docs/content-delivery-api/deep-filtering.md)
- [Ordering records](https://www.datocms.com/docs/content-delivery-api/ordering-records.md)
- [Pagination](https://www.datocms.com/docs/content-delivery-api/pagination.md)
- [Localization](https://www.datocms.com/docs/content-delivery-api/localization.md)
- [Direct vs. Inverse relationships](https://www.datocms.com/docs/content-delivery-api/inverse-relationships.md)
- [Hierarchical sorting (Tree-like collections)](https://www.datocms.com/docs/content-delivery-api/hierarchical-sorting.md)
- [Modular content fields](https://www.datocms.com/docs/content-delivery-api/modular-content-fields.md)
- [Structured text fields](https://www.datocms.com/docs/content-delivery-api/structured-text-fields.md)
- [Images and videos](https://www.datocms.com/docs/content-delivery-api/images-and-videos.md)
- [Filtering uploads](https://www.datocms.com/docs/content-delivery-api/filtering-uploads.md)
- [SEO and favicon fields](https://www.datocms.com/docs/content-delivery-api/seo-and-favicon.md)
- [Meta fields](https://www.datocms.com/docs/content-delivery-api/meta-fields.md)
- [Cache Tags Overview](https://www.datocms.com/docs/content-delivery-api/cache-tags.md)
- [Cache tags in CDA responses](https://www.datocms.com/docs/content-delivery-api/cache-tags-format.md)
- [The cache tags invalidation webhook](https://www.datocms.com/docs/content-delivery-api/cache-tags-invalidation.md)
- [Integrating cache tags in your project](https://www.datocms.com/docs/content-delivery-api/cache-tags-integrations.md)
- [Error codes & handling failures (CDA)](https://www.datocms.com/docs/content-delivery-api/errors.md)
- [CDA Technical Limits & Rate Limits](https://www.datocms.com/docs/content-delivery-api/technical-limits.md)
- [Complexity](https://www.datocms.com/docs/content-delivery-api/complexity.md)
- [Custom Scalar Types](https://www.datocms.com/docs/content-delivery-api/custom-scalar-types.md)
- [Changelog](https://www.datocms.com/docs/content-delivery-api/changelog.md)