Learn more about error codes and how to resolve them.

Herald uses HTTP response status codes to indicate the success or failure of an API request.

  • Codes in the [.h-code]2xx[.h-code] range indicate success.
  • Codes in the [.h-code]4xx[.h-code] range indicate an error that failed given the information provided.
  • Codes in the [.h-code]5xx[.h-code] range are rare and indicate an error with Herald.

For failed requests (codes in the [.h-code]4xx[.h-code] or [.h-code]5xx[.h-code] range), Herald will send back an array of error objects. This array of error objects will contain all known errors for the most relevant HTTP status code.

HTTP status codes

Status Code Description
200 (OK) Everything worked as expected.
400 (Bad Request) The format or content of your request is invalid.
401 (Unauthorized) No valid API key provided.
404 (Not Found) The resource doesn't exist.
429 (Too Many Requests) Too many requests hit the API too quickly. Our current limits in both Sandbox and Production are 120 requests per minute.
500 (Server Error) Something went wrong with Herald.

Error schema

[.icon-circle-blue][.icon-circle-blue] See our full [.h-endpoint-link]error schema[.h-endpoint-link] in our API reference.
id string
A unique error ID for error tracking and support.
code string
A short string indicating the error reported.
Allowed values:
unauthorized not_found http_not_supported invalid_method invalid_format invalid_request internal_server_error
message string
Details about the specific manifestation of the error.
display_message string
A user-friendly representation of what caused the error, safe to be formatted on a front-end. Currently only includes a value for errors caused by risk and coverage parameters.
length must be 5 characters long
path string
If the error is parameter-specific, included a path to the specific parameter. Useful for rendering error messages below inputs on the front end. Only includes a value for errors causes by risk and coverage parameters.



    "errors": [
            "id": "a328ffb9-631a-4c21-9d4e-9f3a213b7bcd",
            "code": "invalid_format",
            "message": "\"risk_values[2].value.postal_code\" length must be 5 characters long",
            "display_message": "length must be 5 characters long",
            "path": "risk_values[2].value.postal_code"

Error codes

Code HTTP Status Description
http_not_supported 400 Request was made over http instead of https.
invalid_method 400 An invalid HTTP method was used for the path provided.
invalid_format 400 The request was not in a valid format.
invalid_request 400 The content of your request was not valid.
unauthorized 401 No valid bearer token provided.
not_found 404 Attempt to get a resource that does not exist.
internal_server_error 500 Herald error.