Upcoming: Changes to error responses

In an effort to make error messages from the HubSpot APIs cleaner and easier to understand, we'll be making a few changes to the fields included in our error responses.

The requestId field will be removed from responses

Beginning in January 2020, the requestId field will no longer be included in responses. This field has never served any real purpose, and is effectively redundant as a unique ID for a request, as we'll be leaving the correlationId field as is.

If your integration uses the requestId field for any type of logging, you'll want to switch to using the correlationId instead. The correlationId field will also be unique for each request.

This field will no longer be included in responses beginning on January 3, 2020.

Two new fields are being added to responses from certain APIs

In an effort to make errors easier to understand, we'll be adding two new fields to some of our APIs over the next few weeks.

These fields are:

• category - This will be the general category of the error. For example, this field will be set to "RATE_LIMITS" for any errors resulting from exceeding our API rate limits, or "VALIDATION_ERROR" for any errors resulting from invalid data being included in the request.
• errors - This will be an array of objects that include more details for any errors that occurred. Each entry will include a message field that will be a human readable string with more details about the error.

The format for these fields will be:

{
  "status": "error",
  "message": "This will be a human readable message with details about the error.",
  "errors": [
    {
      "message": "This will be a message with additional details about the error",
      "in": "fieldname"
    }
  ],
  "category": "VALIDATION_ERROR",
  "correlationId": "a43683b0-5717-4ceb-80b4-104d02915d8c"
}

The new errors array will make it easier to parse the response when there are multiple errors. The new messages will also have updated wording with more detailed explanations of the error.

The existing top-level message field currently included in error responses will not be removed. However, the top-level field is not being updated at this time and will not have the updated, more detailed explanations.

One important note for these fields is that they are being rolled out separately for individual APIs over the coming weeks. As such, these fields must be treated as optional in any error parsing that you have.

Please let us know if you have any questions by joining the discussion in our forums.