Json api error response

# Introduction

The JSON:API specification defines error objects (opens new window)
that are used to provide information to a client about problems encountered
while performing an operation.

Errors are returned to the client in the top-level errors member of the
JSON document.

Laravel JSON:API makes it easy to return errors to the client — either
as responses, or by throwing exceptions. In addition, the exception
renderer you added to your exception handler during
installation takes care of
converting standard Laravel exceptions to JSON:API error responses
if the client has sent an Accept: application/vnd.api+json header.

# Error Objects

Use our LaravelJsonApiCoreDocumentError object to create a JSON:API
error object. The easiest way to construct an error object is using the
static fromArray method. For example:

The fromArray method accepts all the error object members
defined in the specification. (opens new window)

Alternatively, if you want to use setters, use the static make method
to fluently construct your error object:

The available setters are:

• setAboutLink
• setCode
• setDetail
• setId
• setLinks
• setMeta
• setStatus
• setSource
• setSourceParameter
• setSourcePointer
• setTitle

# Error Lists

If you need to return multiple errors at once, use our
LaravelJsonApiCoreDocumentErrorList class. This accepts any number
of error objects to its constructor. For example:

Use the push method to add errors after constructing the error list:

# Responses

Both the Error and ErrorList classes implement Laravel’s Responsable
interface. This means you can return them directly from controller actions
and they will be converted to a JSON:API error response.

If you need to customise the error response, then you need to use our
LaravelJsonApiCoreResponsesErrorResponse class. Either create
a new one, passing in the Error or ErrorList object:

Or alternatively, use the prepareResponse method on either the Error
or ErrorList object:

The ErrorResponse class has all the helper methods
required to customise both the headers and the JSON:API document that
is returned in the response.

For example, if we were adding a header and meta to our response:

# HTTP Status

The JSON:API specification says:

When a server encounters multiple problems for a single request,
the most generally applicable HTTP error code SHOULD be used in the response.
For instance, 400 Bad Request might be appropriate for multiple 4xx errors
or 500 Internal Server Error might be appropriate for multiple 5xx errors.

Our ErrorResponse class takes care of calculating the HTTP status for you.

If there is only one error, or all the errors have the same status, then
the response status will match this status.

If you have multiple errors with different statuses, the response status
will be 400 Bad Request if the error objects only have 4xx status codes.
If there are any 5xx status codes, the response status will be
500 Internal Server Error.

If the response has no error objects, or none of the error objects have a
status, then the response will have a 500 Internal Server Error status.

If you want the response to have a specific HTTP status, use the
withStatus method. For example:

# JSON:API Exceptions

Our LaravelJsonApiCoreExceptionsJsonApiException allows you to terminate
processing of a request by throwing an exception with JSON:API errors
attached.

The exception expects its first argument to be either an Error or an
ErrorList object. For example:

The JsonApiException class has all the helper methods
required to customise both the headers and the JSON:API document that
is returned in the response. Use the static make method if you need to
call any of these methods. For example:

There is also a handy static error method. This allows you to fluently
construct an exception for a single error, providing either an Error
object or an array. For example:

# Helper Methods

The JsonApiException class has a number of helper methods:

• is4xx
• is5xx
• getErrors

# is4xx

Returns true if the HTTP status code is a client error, i.e. in the 400-499
range.

# is5xx

Returns true if the HTTP status code is a server error, i.e. in the 500-599
range.

# getErrors

Use the getErrors() method to retrieve the JSON:API error objects from the
exception. For example, if we wanted to log the errors:

# Validation Errors

Our implementation of resource requests and
query parameter requests already takes
care of converting Laravel validation error messages to JSON:API errors.

If however you have a scenario where you want to convert a failed validator
to JSON:API errors manually, we provide the ability to do this.

You will need to resolve an instance of LaravelJsonApiValidationFactory
out of the service container. For example, you could use the app helper,
or use dependency injection by type-hinting it in a constructor of a service.

Once you have the factory instance, use the createErrors method,
providing it with the validator instance. For example, in a controller
action:

The object this returns is Responsable — so you can return it directly
from a controller action. If you want to convert it to an error response,
use our prepareResponse pattern as follows:

# Source Pointers

By default this process will convert validation error keys to JSON source
pointers. For example, if you have a failed message for the foo.bar
value, the resulting error object will have a source pointer of
/foo/bar.

If you need to prefix the pointer value, use the withSourcePrefix method.
The following example would convert foo.bar to /data/attributes/foo/bar:

If you need to fully customise how the validation key should be converted,
provide a Closure to the withPointers method:

# Error Rendering

As described in the installation instructions,
the following should have been added to the register method on your
application’s exception handler:

The Laravel exception handler already takes care of converting exceptions to
either application/json or text/html responses. Our exception handler
effectively adds JSON:API error responses as a third media type. If the
client has sent a request with an Accept header of application/vnd.api+json,
then they will receive the exception response as a JSON:API error response —
even if the endpoint they are hitting is not one of your JSON:API server
endpoints.

# JSON Responses

If a client encounters an exception when using an Accept header of
application/json, they will still receive Laravel’s default JSON exception
response, rather than a JSON:API response.

If you want our exception parser to render JSON exception responses instead
of the default Laravel response, use the acceptsJson() method when registering
our exception parser:

# Middleware Responses

Sometimes you may want exceptions to be converted to JSON:API errors if the
current route has a particular middleware applied to it. The most common example
of this would be if you want JSON:API errors to always be rendered if the
current route has the api middleware.

In this scenario, use the acceptsMiddleware() method when registering our
exception parser. For example:

# Always Rendering JSON:API Errors

If you want our exception parser to always convert exceptions to JSON:API
errors, use the acceptsAll() helper method:

# Custom Rendering Logic

If you want your own logic for when a JSON:API exception response should be
rendered, pass a closure to the accept() method.

For example, let’s say we wanted our API to always return JSON:API exception
responses, regardless of what Accept header the client sent. We would use
the request is() method to check if the path is our API:

# Converting Exceptions

Our exception parser is built so that you can easily add support for
custom exceptions to the JSON:API rendering process. The implementation works
using a pipeline, meaning you can add your own handlers for converting
exceptions to JSON:API errors.

For example, imagine our application had a PaymentFailed exception, that
we wanted to convert to JSON:API errors if thrown to the exception handler.
We would write the following class:

We can then add it to the JSON:API exception parser using either the
prepend or append method:

# Error Reporting

As described in the installation instructions,
the following should have been added to the $dontReport property on your
application’s exception handler:

This prevents our JsonApiException from being reported in your application’s
error log. This is a sensible starting position, as the JsonApiException
class is effectively a HTTP exception that needs to be rendered to the client.

However, this does mean that any JsonApiException that has a 5xx status
code (server-side error) will not be reported in your error log. Therefore,
an alternative is to use the helper methods on the JsonApiException class
to determine whether or not the exception should be reported.

To do this, we will use the reportable() method to register a callback
for the JSON:API exception class. (At the same time, we remove the exception
class from the $dontReport property.) For example, the following will stop
the propagation of JSON:API exceptions to the default logging stack if the
exception does not have a 5xx status:

In the following example, we log 4xx statuses as debug information, while
letting all other JSON:API exceptions propagate to the default logging stack: