Skip to content
MundoProgra JSON:API
Menu

Guide

Errors

Every error comes out as {"errors": [...]} with status, title, detail, code and source (pointer, parameter or header), in the app language (Spanish and English included).

The package hooks into Laravel's exception handling and works the same on versions 10 to 13; if the app registers its own renderable, the app's wins. To throw one by hand:

throw JsonApiException::make(status: 404, pointer: '/data/relationships/author/data');

The title, detail and code are filled in from the status. A 5xx error hides its internals unless errors.expose_details (or app.debug) allows it.

Error codes

Base codeStatusWhen
request.not_acceptable406The Accept does not allow JSON:API (source.header)
request.unsupported_media_type415The Content-Type is not JSON:API (source.header)
request.bad_query400A malformed or not allowed query parameter (source.parameter)
request.bad_document400The body is not JSON or does not have the shape of a document (source.pointer)
request.bad_request400A malformed request that is neither a query nor a document problem
request.client_id_not_allowed403A POST with a client id and allow_client_ids off
auth.unauthenticated401Not authenticated; it never redirects to login
auth.forbidden403No permission
auth.invalid_signature403The signed URL is invalid or expired
resource.not_found404The resource does not exist (it does not reveal the model name)
route.not_found404The route does not exist
request.method_not_allowed405The method is not on the route; it carries Allow
resource.conflict409The type or id of the document are not those of the endpoint
request.payload_too_large413The request body exceeds the limit
request.token_mismatch419The CSRF or session token expired
validation.<rule> / validation.failed422A validation rule failed (validation.required, validation.max…); validation.failed when there is no rule name
request.too_many_requests429Rate limit; it carries Retry-After
server.error / server.unavailable500 / 503Unexpected error or service unavailable

Any other HTTP status uses http.<status> (for example http.402). Codes carry the prefix mundoprogra.json-api. (for example mundoprogra.json-api.validation.required). Change it with errors.code_prefix, replace codes one by one with errors.codes, or turn them off with errors.include_code.

The order of the checks

When a request fails for more than one reason, only the first comes out, in this order:

  1. Content-Type (415) and then Accept (406).
  2. The syntax of the query (400).
  3. The document: broken or malformed JSON (400) or a client id (403).
  4. The route: method not allowed (405) or a route that does not exist (404).
  5. Authentication (401).
  6. The FormRequest: a different type or id (409) and then the rules (422).
  7. Your controller: the query whitelist (400) and a resource that does not exist (404).

Steps 1 to 3 run before auth: without a session, broken JSON is a 400, not a 401.