Unless otherwise specified, most HubSpot APIs will return a 200 OK response on success.  Any endpoints that return a different status code will specify the returned response on the individual documentation page for that endpoint.

In addition, HubSpot has several error responses that are common to multiple APIs.

• 401 Unauthorized - Returned when the authentication provided is invalid.  See our authentication overview for details on authenticating API requests.
• 403 Forbidden - Returned when the authentication provided does not have the proper permissions to access the specific URL.  As an example, an OAuth token that only has Content access would get a 403 when accessing the Deals API (which requires Contacts access).
• 429 Too many requests - Returned when your portal or app is over the API rate limits. Please see this document for details on those rate limits and suggestions for working within those limits.
• 502/504 timeouts - HubSpot has processing limits in place to prevent a single client causing degraded performance, and these responses indicate that those limits have been hit.  You'll normally only see these timeout responses when making a a large number of requests over a sustained period.  If you get one of these responses, you should pause your requests for a few seconds, then retry.

Aside from those general errors, HubSpot error responses are intended to be human readable. Most endpoints do not return error codes, but return a JSON formatted response with details about the error.

Note: The fields in the example response below should all be treated as optional in any error parsing. The specific fields included can vary between different APIs, so any error parsing should allow for specific fields to be missing from the response.

{
  "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": "name"
    }
  ],
  "category": "VALIDATION_ERROR",
  "correlationId": "a43683b0-5717-4ceb-80b4-104d02915d8c"
}

More details for endpoint specific errors can be found on the documentation pages for the endpoint.