Reaching plan monthly limit/payment errors

🆘 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