Reaching plan monthly limit/payment errors. Is there a list of CMA and CDA error codes? [Modified title]

🆘 Support
1

Hi, we’re working to improve our application’s behavior during error conditions.

The general error page for the Content Management API is nice: https://www.datocms.com/docs/content-management-api/errors but there doesn’t seem to exist such a page for the Content Delivery API. That would be useful, especially if it also included HTTP codes, to get more information about possible error states.

This page: https://www.datocms.com/docs/content-delivery-api/technical-limits#rate-limits indicates that HTTP status 429 may be returned but are there other statuses you use for other error conditions? For example if payments fail for an extended time what HTTP status will you return then? It would be useful if that was documented on: https://www.datocms.com/docs/content-delivery-api/technical-limits#reaching-your-plan-monthly-api-calls-limit

Knowing at least some of the main error codes would help us build a robust application that can properly explain potential errors for users and inform our developers on how to react when facing errors.

2

Hi @gabriel1,

Great question. Let me try to find out some detailed error codes for you!

1 Like
4

@gabriel1,

Just a note that we will be discussing this internally soon. It’s a good idea, but also a complex enough project that we’ll have to scope it out and figure out how to best go about doing this. I’ll provide updates when I can!

5

Hey @gabriel1,

Good news: We overhauled our API output and now have documented error codes!

https://www.datocms.com/docs/content-management-api/errors now lists several dozen error codes and their meanings.

Please note that because there are many different possible errors, you should check for HTTP response code != 2xx and then parse the JSON body’s data.map(error => error.code) for the actual error. An example error response might look like:

{
  "data": [
    {
      "id": "ce9dcb",
      "type": "api_error",
      "attributes": {
        "code": "INVALID_FIELD",
        "doc_url": "https://www.datocms.com/docs/content-management-api/errors#INVALID_FIELD",
        "details": {
          "field": "api_key",
          "code": "VALIDATION_UNIQUENESS",
          "record_type": "ItemType"
        }
      }
    }
  ]
}

The parent INVALID_FIELD is then explained here: https://www.datocms.com/docs/content-management-api/errors#INVALID_FIELD (the inner error code is not yet parsed, but hopefully it’s clear enough).

We also have a machine-parseable JSON of the explanations, in case you want to include this in your own project: https://site-api.datocms.com/docs/site-api-errors.json

Thanks again for the suggestion. Please let us know if you have any feedback.

6

I clarified the situation with the HTTP codes, by the way. The overwhelming majority of them will return a 4xx, and only rarely a 5xx (generally an unhandled/unexpected error of some sort). It’s still safer to check for !2xx rather than specifically a 4xx or 5xx. And rather than parsing the HTTP status code, it will be more informative to parse the attributes.code in the JSON body and reference that against either the human-readable error codes documentation or the machine-parseable JSON version of the same codes.

Probably the monthly plan error would be PLAN_UPGRADE_REQUIRED

1 Like
7

Very nice documentation, thank you! :pray: :heart:

1 Like
8

@roger, I had a look again and realize that while this error docs are very nice they are not for the correct API :sweat_smile:. I think the Content Delivery API is more interesting as this is the API that is most likely to affect our site in production.

We had outages due to payment issues + our billing email being that of a former employee and we didn’t properly handle the errors we got from the Content Delivery API when that happened.

A similar set of docs for that API would be very useful!

10

Hmm, so sorry I totally missed that! Let me double-check with the devs for you on that.

There should be far fewer CDA error codes since you can’t mutate (create/update) records through it, but yeah, it would still be helpful to know when it fails due to a rate limit, query error, plan limit, etc.

11

We’re going to try to enumerate the CDA errors in a docs page soon, but it might take a bit of time (there’s some unrelated higher-priority stuff that needs to be taken care of first).

In the meantime, for the purposes of catching errors, you should just check for a status !== 200 instead of a particular 4xx or 5xx code. If you ever get a non-200 response, look for a JSON body and log the error message in there.

We’ll enumerate and detail them soon, though!

13

@gabriel1, sorry it took a while to compile these! The different errors come from different places and a dev had to manually compile them. Here’s the list we have so far for the CDA:

I will update the documentation pages with these same codes shortly, but just wanted you to have them here first.

Content Delivery API Error Codes & Meanings

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

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

14

I’ve updated the documentation and clarified both sets now:

Hope that helps!