Error Responses

When an API request fails, the response body contains an error object with details about what went wrong.

Error Response Shape

{
  "error": {
    "status": 400,
    "name": "BadRequestError",
    "message": "A description of what went wrong.",
    "data": {}
  }
}

Field	Type	Description
`status`	Number	The HTTP status code.
`name`	String	The error class name.
`message`	String	A human-readable description of the error.
`data`	Object	Additional context, when available.

Status Codes

Status	Name	Description
`400`	Bad Request	The request is malformed or contains invalid parameters.
`401`	Unauthorized	Missing or invalid API key. See Authentication.
`404`	Not Found	The requested Advice Set or resource does not exist.
`500`	Internal Server Error	An unexpected error occurred on the server.

Incomplete Advice

In some cases, the API returns a 200 status with advice in an incomplete state. This occurs when the Rules Engine encounters an evaluation error for a specific rule, but other rules in the Advice Set evaluate successfully.

An incomplete advice item will have a type of EvaluatorError rather than ADVICE:

{
  "data": {
    "advice": [
      {
        "type": "ADVICE",
        "headline": "Your contribution limit is $7,000."
      },
      {
        "type": "EvaluatorError",
        "headline": null,
        "message": "An error occurred evaluating this rule."
      }
    ]
  }
}

Check the type field on each advice item to identify and handle these cases in your integration.