Error Scheme

gistfile1.txt

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

{
    "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"
                ]
            }
        ]
    }
}

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

{
  "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"
    }
  ]
}