Handling Errors

When the API returns an error, it will include three key pieces of information: an HTTP status code, an internal tracking code, and a human-readable message.

Error structure

Below are some simple examples of the general structure for an error response.

{
    "error": {
        "code": 0,
        "reference_id": null,
        "more_info": "http://api.spoonity.com/doc/#apiMethod",
        "errors": [
            {
                "reason": "exception",
                "message": "Requested vendor is not valid"
            }
        ]
    },
    "object": "error"
}

In most cases, the most important piece of information will be the message field inside the errors array. This field is used to provide a human-readable explanation of the error message, and is often safe to share directly with the user.

In some cases, a code or reference_id field will be included, which can be shared with Spoonity support to help troubleshoot more complex or opaque issues.

Finally, while we strive to use common-sense HTTP status codes whenever possible, there may be some occasions where this is not possible. An example of this would be for order-based errors when interacting with the POST /orders API. Because some of the legacy systems we work with are not able to handle non-HTTP 2XX codes, we will sometimes return an HTTP 200 status code, with a success:false field inside the JSON response payload.

Localization

At this time, error messages from the API are not localized. As we continue to improve and update our API, we will be taking specific steps to improve this experience for our integration partners.