Overview of errors/error codes that can happen for endpoints

[#1]

Hey there,

#Question:
Is there a documentation for an overview of all errors that can occur for a certain endpoint? Currently most important are the contact and deals api.

#Background:
We would like catch certain errors from the hubspot api in our application and act accordingly. The problem is that we don’t have a list of errors we can possible catch. So we need either try manuelly the routes and see what happen or see what errors occur when the integration is running in production. Both ways are suboptimal as there are either going on our rate limit and waste time or we can just react after errors appear and not before hand.

[Derek_Gervais]

Hi @H3xas,

Error documentation still lives in specific documentation pages; there isn't an authoritative list/table of all of HubSpot's error messages. As David mentioned, the only global error response is the 429 rate limit error (see above).

[RafalCzabaj]

Hi @Derek_Gervais @dadams

List of error messages is something that would be helpful for us. If that is internal only, that is okay.

However the problem on our side is that each kind of API endpoint has different response format. Therefore we have lost for some time many error messages, as we didn't know the structure of an error.

I will explain that with an example presented below.
The error structure of each object is specified within the information that you linked limits.

However the error response for single hubspot contact api looks has following format:

{
  "status": "error",
  "message": "Property values were not valid",
  "correlationId": "2256d2c8-25a3-41c5-ad3e-12e42d9c84b3",
  "validationResults": [
    {
      "isValid": false,
      "message": "Open deal was not allowed option [...]",
      "error": "INVALID_OPTION",
      "name": "fieldname"
    }
  ],
  "requestId": "47f86607028b5bdbbd8bc225e7e9f468"
}

As you can see for this endpoint this is the structure. The problem exists as this is not structured anywhere and as we have a middleware solution that connects multiple softwares we have to build our custom error handling mechanism based on your responses. It took us some time to understand all possibilities that we had. However after that we have moved to the HubSpot Contact Batch API.
And this is the response of them:

{
  "status": "error",
  "message": "Errors found processing batch update",
  "correlationId": "0e3f68b0-e084-4e1f-a451-6c51d96aa29f",
  "failureMessages": [
    {
      "index": 1,
      "propertyValidationResult": {
        "isValid": false,
        "message": "20 was not one of the allowed options: [label: \"English (English)\" value: \"1\" hidden: false read_only: false, label: \"Fran\303\247ais (French)\" value: \"2\" hidden: false read_only: false, label: \"Deutsch (German)\" value: \"3\" hidden: false read_only: false, label: \"Nederlands (Dutch)\" value: \"4\" hidden: false read_only: false]",
        "error": "INVALID_OPTION",
        "name": "language"
      }
    }
  ],
  "requestId": "5ce68383f81f8fdc6eaba63abdb76dc3"
}

Here the format of the response changed (it is still similar) however without the modifications of the response model and everything, we still lost a lot of messages as we were not aware of the response message format.

Conclusion: I don't know if using the HubSpot Company Batch API has similar structure or any other similar way of sending errors. Therefore this is the reason why I am asking the update documentation for the error response (not only messages), as this really makes our life easier (and I can bet I am not alone here with this issue).

Kind Regards,
Rafal

[Dadams]

Hi @mupat

Any documentation for errors would be on the specific documentation pages. The only global error response would be 429 responses returned for exceeding our rate limits.

Otherwise, 4xx errors usually indicate problems with the data in the request, either with the format with the JSON or with the data itself (invalid options for enumerated properties, setting a property that doesn’t exist, etc). There will be more details for the specific problem in the response message, but in general those errors should not be retried automatically.

[RafalCzabaj]

Hi @dadams

It has been over 2 years since the creation of this post.
Is there already some documentation of the possible error codes / responses
or at least it is under development?

This would be really helpful for the development team, to have better understanding of error
codes for error handling mechanism development.

Kind Regards,
Rafal