Saltar al contenido
MundoProgra JSON:API
Menú

Guía

Errores

Todo error sale como {"errors": [...]} con status, title, detail, code y source (pointer, parameter o header), en el idioma de la app (español e inglés incluidos).

El paquete se engancha al manejo de excepciones de Laravel y sale igual en las versiones 10 a 13; si la app registra su propio renderable, el de la app gana. Para lanzar uno a mano:

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

El título, el detalle y el código se completan solos a partir del estado. Un error 5xx oculta sus detalles internos salvo que errors.expose_details (o app.debug) lo permita.

Códigos de error

Código baseEstadoCuándo
request.not_acceptable406El Accept no permite JSON:API (source.header)
request.unsupported_media_type415El Content-Type no es JSON:API (source.header)
request.bad_query400Un parámetro de consulta mal formado o no permitido (source.parameter)
request.bad_document400El cuerpo no es JSON o no tiene la forma de un documento (source.pointer)
request.bad_request400Una petición mal formada que no es de consulta ni de documento
request.client_id_not_allowed403Un POST con id del cliente y allow_client_ids apagado
auth.unauthenticated401Sin autenticar; nunca redirige al login
auth.forbidden403Sin permiso
auth.invalid_signature403La URL firmada es inválida o venció
resource.not_found404El recurso no existe (no revela el nombre del modelo)
route.not_found404La ruta no existe
request.method_not_allowed405El método no está en la ruta; lleva Allow
resource.conflict409El type o el id del documento no son los del endpoint
request.payload_too_large413El cuerpo de la petición supera el límite
request.token_mismatch419El token CSRF o de sesión venció
validation.<regla> / validation.failed422Una regla de validación falló (validation.required, validation.max…); validation.failed si no hay nombre de regla
request.too_many_requests429Límite de peticiones; lleva Retry-After
server.error / server.unavailable500 / 503Error inesperado o servicio no disponible

Cualquier otro estado HTTP usa http.<estado> (por ejemplo http.402). Los códigos llevan el prefijo mundoprogra.json-api. (por ejemplo mundoprogra.json-api.validation.required). Se cambia con errors.code_prefix, se reemplazan uno a uno con errors.codes o se apagan con errors.include_code.

El orden de las comprobaciones

Cuando una petición falla por más de un motivo, sale solo el primero, en este orden:

  1. Content-Type (415) y después Accept (406).
  2. La sintaxis de la consulta (400).
  3. El documento: JSON roto o mal formado (400) o un id del cliente (403).
  4. La ruta: método no permitido (405) o ruta que no existe (404).
  5. La autenticación (401).
  6. El FormRequest: type o id distintos (409) y después las reglas (422).
  7. Tu controlador: la lista blanca de la consulta (400) y el recurso que no existe (404).

Los pasos 1 a 3 corren antes que auth: sin sesión, un JSON roto es un 400 y no un 401.