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.

{
 "status": "error",
 "message": "This will be a human readable message with more details of the problem",
 "correlationId": "a2d3acb6-f78c-476e-9811-860509ae9e20",
 "requestId": "a43683b0-5717-4ceb-80b4-104d02915d8c"
}

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