Skip to content

Instantly share code, notes, and snippets.

@kenelliott
Last active August 29, 2015 14:16
Show Gist options
  • Save kenelliott/39d3a93a7affe9edbaed to your computer and use it in GitHub Desktop.
Save kenelliott/39d3a93a7affe9edbaed to your computer and use it in GitHub Desktop.
Error Scheme
Google JSON StyleGuide
link: https://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml?showone=error.code#error.code
{
"apiVersion": "2.0",
"error": {
"code": 404,
"message": "File Not Found",
"errors": [{
"domain": "Calendar",
"reason": "ResourceNotFoundException",
"message": "File Not Found"
}]
}
}
JSON-API
link: http://jsonapi.org/format/#errors
{
"errors": [
{
"id": 1,
"href": "http://link-to-error-information-i-guess",
"status": 422,
"code": "unprocessable_entity",
"title": "Request could not be completed because record validations failed.",
"detail": "Properties on the object did not pass validations.",
"links": [
"resource_name": "http://path-to-api/resource_name"
],
"paths": [
"property_name": "/property_name"
]
}
]
}
These recommendations are complex and if I were to pick one I would choose JSON-API version. Currently
we use the format below. It works for all intents and purposes, but overly simplifies the purpose of
the error object, side-steps internationalization resulting in no translations for errors and does not
handle external errors particularly well. e.g. Braintree, Conduit - errors from these services are
merely channeled through verbatim and are either jammed into the base object or they stray from the
propsed format and cause confusion in the error parsing.
{
“errors”: {
“base”: [
“you can not do that”,
“nice try haxor”
],
“first_name”: [
“can not be blank”,
“must include a capital letter”
],
“address.city”: [
“must include some numbers”,
“must be located on earth”
]
}
Questions to reconcile:
1. internationalization
2. error lists for properties. i.e first_name: ["must be more than 2 letters", "must begin with a capital letter"]
3. errors for nested objects e.g. warehouse.location.name, subscriber.address.city
4. external services e.g. braintree.credit_card.exp_year
5. extended error explainations for API consumers (links to documentation as suggested in the json-api)
6. unique error codes
@kenelliott
Copy link
Author

{
    "error": {
        "type": "invalid_request",
        "errors": [ 
            {
                "param": "first_name",
                "messages": [
                    "first name is required", 
                    "first name can not be Darth"
                ]
            },
            {
                "param": "credit_card.ccv",
                "messages": [
                    "ccv must be 3 characters", 
                    "ccv can not be 123"
                ]
            }
        ]
    }
}

@kenelliott
Copy link
Author

{
  "errors": [
    {
      "type": "field_presence",
      "field": "nid",
      "message": "NID cannot be blank"
    },
    {
      "type": "field_uniqueness",
      "field": "nid",
      "message": "NID must be unique"
    },
  ]
}

@kenelliott
Copy link
Author

{
  "errors": [
    {
      "code": "field_presence",
      "field": "name",
      "resource": "warehouse",
      "message": "Name is required"
    },
    {
      "code": "resource_presence",
      "field": "",
      "resource": "warehouse.address",
      "message": "Address is required"
    },
    {
      "code": "field_presence",
      "field": "city",
      "resource": "warehouse.address.city",
      "message": "City is required"
    }
  ]
}

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment