JSON API Error Objects

The JSON API specification version 1.0 stated that an error object MAY have the following members:

• id: a unique identifier for this particular occurrence of the problem.
• links: a links object containing the following members:
  • about: a link that leads to further details about this particular occurrence of the problem.
• status: the HTTP status code applicable to this problem, expressed as a string value.
• code: an application-specific error code, expressed as a string value.
• title: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
• detail: a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.
• source: an object containing references to the source of the error, optionally including any of the following members:
  • pointer: a JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].
  • parameter: a string indicating which URI query parameter caused the error.
• meta: a meta object containing non-standard meta-information about the error.

Error Object members

For each member this package has an equivalent key in the associative Error Object array. All members are optional, except the title member when raising an error that exists on Application Error Codes class.

Id

The id member is equivalent to the same id key in this package. It may be an integer or a string.

'id' => 'unique-identifier'

Links

The links member is equivalent to the same links key in this package. It must be an associative array that must have href key and may have meta key. If meta key is provided it must be another associative array representing an object.

'links' => [
  'href' => 'http://example.com/specific/link/to/the/problem',
  'meta' => [
    'attribute1' => 'value',
    'attribute2' => 123
  ]
]

Status

The status member is auto generated by the specific error function you call or by the second parameter of the generic error function.

MyJsonApiErrors::badRequest(...);

MyJsonApiErrors::error(..., 500);

In the first code status will be 400 equivalent to a HTTP Bad Request Error, and in the second code status will be 500 manually given and equivalent to a HTTP Internal Server Error.

These functions will be covered in the chapter Error Functions.

Code

The code member is equivalent to the key on $errors static property of your own class or the associative array provided to the error function that will be raised. It must be integer and will be auto converted to string. In the example below the code member is the value of constant PAGE_INVALID_PARAMETER

self::PAGE_INVALID_PARAMETER => [
  'title' => 'Invalid Parameter',
  'detail' => 'The parameter given is invalid.',
  'method' => 'queryParameter',
  'parameter' => 'page'
],

Title

The title member is equivalent to the same title key in this package. It must be a string.

'title' => 'Invalid Parameter'

When raising an error that exists on Application Error Codes class this is the only member that can not be null and is required.

Detail

The detail member is equivalent to the same detail key in this package. It must be a string.

'detail' => 'The parameter given is invalid.'

Source

The source member is equivalent to the method key that may be used together with the parameter key in this package. Both must be a string.

'method' => 'data'

'method' => 'queryParameter',
'parameter' => 'page'

In the JSON API specification version 1.0 this member may have a pointer and a parameter member that will be auto generated according to the method and parameter provided in this package.

Available methods

We can split the available methods in two groups:

1. The methods that do not have a parameter: data, dataType, dataId and relationships.
2. The methods that must have a parameter: dataAttribute, relationship, relationshipType, relationshipId and queryParameter.

Each method will generate a specific source member that may have pointer or parameter:

'method' => 'data'
//will output
"source": {
  "pointer": "/data"
}

'method' => 'dataType'
//will output
"source": {
  "pointer": "/data/type"
}

'method' => 'dataId'
//will output
"source": {
  "pointer": "/data/id"
}

'method' => 'dataAttribute',
'parameter' => 'attributeName'
//will output
"source": {
  "pointer": "/data/attributes/attributeName"
}

'method' => 'relationships'
//will output
"source": {
  "pointer": "/data/relationships"
}

'method' => 'relationship',
'parameter' => 'relationshipName'
//will output
"source": {
  "pointer": "/data/relationships/relationshipName"
}

'method' => 'relationshipType',
'parameter' => 'relationshipName'
//will output
"source": {
  "pointer": "/data/relationships/relationshipName/type"
}

'method' => 'relationshipId',
'parameter' => 'relationshipName'
//will output
"source": {
  "pointer": "/data/relationships/relationshipName/id"
}

'method' => 'queryParameter',
'parameter' => 'parameterName'
//will output
"source": {
  "parameter": "parameterName"
}

Meta

The meta member is equivalent to the same meta key in this package. It must be an associative array representing an object.

'meta' => [
  'attribute1' => 'value',
  'attribute2' => 123
]

← Application Error Codes | Raising Application Errors →