Envelope JSON & Tratamento de Erros v4

A helper json() emite respostas com Content-Type: application/json, status HTTP e encerramento seguro.

`json()`

json($data);                    // 200
json($data, 201);               // Created
json($data, 200, ['X-Cache' => 'HIT']);

Parâmetro	Tipo	Padrão	Descrição
`$data`	mixed	—	Array, Collection, Model ou string
`$status`	int	`200`	Status HTTP
`$headers`	array	`[]`	Cabeçalhos extras

Aceita Collections, Models e instâncias de HTTP Data sem json_encode() manual. Para o contrato JSON (campos, relações, paginação), use HTTP Data.

$posts = post::with('category')
    ->where('active', true)
    ->order_by('created_at', 'DESC')
    ->limit(5)
    ->get();

json($posts);

// ou direto no builder
return post::where('active', true)->limit(5)->json();

Exemplos de status

public function show($id)
{
    $post = post::find($id);

    if (!$post) {
        return json([
            'success' => false,
            'message' => 'Postagem não encontrada.',
        ], 404);
    }

    return json([
        'success' => true,
        'data' => $post,
    ]);
}

public function store()
{
    $data = request()->check([
        'title' => 'required|string|max:120',
    ]);

    $post = post::create($data);

    return json([
        'message' => 'Post criado com sucesso!',
        'data' => $post,
    ], 201);
}

Validação JSON (422)

Em rotas API / requests JSON, $request->check() não redireciona — retorna HTTP 422:

{
  "message": "The given data was invalid.",
  "errors": {
    "username": "Informe seu login.",
    "password": "A senha é obrigatória."
  }
}

Detecta JSON quando:

Accept: application/json
Content-Type: application/json
rota começa com /api
ou há Bearer Token

Web continua com redirect + flash errors.

$credentials = $req->check([
    'username' => 'required|string|min:4|max:10',
    'password' => 'required|string|max:10',
], [
    'username.required' => 'Informe seu login.',
    'password.required' => 'A senha é obrigatória.',
]);

JavaScript

if (res.status === 422) {
  const { errors } = await res.json();
  console.log(errors.password);
  Object.entries(errors).forEach(([field, msg]) => {
    console.log(field, msg);
  });
}

C#

if ((int)response.StatusCode == 422) {
    var body = await response.Content.ReadFromJsonAsync<ValidationError>();
    foreach (var (field, msg) in body.Errors)
        Console.WriteLine($"{field}: {msg}");
}

Python

if r.status_code == 422:
    errors = r.json()["errors"]
    for field, msg in errors.items():
        print(field, msg)

Tabela de erros comuns

HTTP	Significado	Envelope
`200` / `201`	Sucesso	Payload livre / `{ success, data }`
`401`	Não autenticado	`{ success: false, code: 401, error: "Unauthenticated" }`
`403`	Ban / allowlist	`{ error: "Origem não autorizada." }`
`404`	Recurso ausente	`{ success: false, message: "..." }`
`422`	Validação	`{ message, errors: { field: msg } }`
`429`	Rate limit	`{ error, retry_after }`

💡Consistência

Padronize { success, data, error } e serialize com HTTP Data. Qualquer client HTTP consome o mesmo JSON.