Errors

All API errors follow a consistent shape. Use the error.code field to handle specific failure modes — don't rely on the HTTP status code alone.

Error object

json

{
  "error": {
    "code": "resource_not_found",
    "message": "No device with id dev_01hxyz was found in this tenant.",
    "request_id": "req_01hxyz",
    "docs_url": "https://hldgroup.org/docs/reference/errors#resource_not_found"
  }
}

HTTP status codes

Name	Type	Required	Description
200 OK	success	No	Request succeeded.
201 Created	success	No	Resource was created.
204 No Content	success	No	Request succeeded with no response body (e.g. DELETE).
400 Bad Request	error	No	Request body or parameters are malformed or missing required fields.
401 Unauthorized	error	No	Missing, invalid, or expired API key.
403 Forbidden	error	No	Valid key but insufficient scope for this operation.
404 Not Found	error	No	Resource does not exist or is not accessible to this key.
409 Conflict	error	No	Resource already exists or a conflicting state prevents the operation.
422 Unprocessable	error	No	Request is well-formed but fails validation (e.g. invalid email, unknown region).
429 Too Many Requests	error	No	Rate limit exceeded. Check Retry-After header.
500 Internal Server Error	error	No	Unexpected server error. Retry with backoff. If persistent, contact support with the request_id.

Error codes

Name	Type	Required	Description
unauthorized	string	No	Invalid or missing API key.
forbidden	string	No	Insufficient scope.
resource_not_found	string	No	The requested resource does not exist.
validation_error	string	No	One or more fields failed validation. Check error.fields for detail.
resource_conflict	string	No	A resource with this identity already exists.
tenant_suspended	string	No	The target tenant is suspended. No operations are permitted.
rate_limited	string	No	Too many requests. Back off and retry.
integration_unavailable	string	No	The target integration is offline or misconfigured.
action_not_reversible	string	No	The requested action cannot be reversed.
internal_error	string	No	Unexpected error. Include request_id when contacting support.

Validation errors

For validation errors, the response includes a fields array:

json

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "request_id": "req_01hxyz",
    "fields": [
      { "field": "contact_email", "message": "Must be a valid email address." },
      { "field": "region", "message": "Must be one of: ap-southeast-2, us-east-1, eu-west-1." }
    ]
  }
}

Rate limits Changelog