Skip to main content
The Mangrove API returns standard HTTP success or error status codes. For errors, the API will also include extra information about what went wrong encoded in the response as JSON. Errors are returned as a list, so one response can report several problems at once:
Every entry carries a message. Validation failures also carry the field the problem is on and a code, and some carry extra keys naming the offending values. A code is a stable slug on the errors that define one, and repeats the message text on the errors that do not, so branch on a code only where you have seen a slug come back. Endpoints that refuse a request without validating a record return a message alone:
A duplicate rule is the one error that also repeats its detail outside the list, as a duplicate_rule sibling of errors, so a client can read it without walking the entries. Its message ends with the existing rule’s effective period in parentheses, which the example above leaves off; read the period from duplicate_rule rather than parsing the text. A 401 from an expired token carries a message saying so. A 401 from a token Mangrove does not recognise carries no body at all, which is how the two are told apart. See Authentication.
The split between 404 and 422 is diagnostic. A 404 points at the path or the record lookup, such as a wrong ID or a record in another account. A 403 is the permission answer, where the token is valid and lacks the permission the endpoint needs. A 422 is business validation, where the request was understood and refused. If a call that used to work starts returning 404, suspect the path or scoping rather than the payload.