Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

A Laravel API call answers with a 302 redirect to a web page

Error302 Found

Short answer

Laravel decides between a redirect and JSON from the request. A form-style request that fails validation gets a 302 back to the previous page, and an unauthenticated one is redirected to the login route. A request that expects JSON gets 422 or 401 instead. Send Accept: application/json, or change the guest redirect.

  • Applies to Laravel 12, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Call the route without following redirects, once with and once without the JSON header, and compare the status line and Location header.

    curl -si -X POST http://localhost:8000/api/posts -d 'title=' | head -n 5
    curl -si -X POST http://localhost:8000/api/posts -H 'Accept: application/json' -d 'title=' | head -n 5
  2. 2Match what you see, then jump to its fix

    1. 1The 302 goes back to the page the request came from, and the status is 422 once the header is added.Validation failed and the request did not ask for JSONFix
    2. 2Location points to /login while the route is under auth middleware.The auth middleware sends guests to the login routeFix

What does the error look like?

  • 302 Found
  • Location: http://localhost/login
  • the API client shows the HTML of your login page, or a redirect to the previous URL

Cause 1 of 2

Validation failed and the request did not ask for JSON

1Check

On a failed validation Laravel throws a ValidationException. A traditional request gets a 302 to the previous URL, while an XHR request or one expecting JSON gets a 422 with the errors as JSON.

curl -si -X POST http://localhost:8000/api/posts -d 'title=' | grep -i -E '^(HTTP|location)'

2Fix

Make the client send Accept: application/json, or an XHR header, on every API call.

curl -X POST http://localhost:8000/api/posts \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"title": ""}'

3Verify

The response is 422 with an errors object.

curl -si -X POST http://localhost:8000/api/posts -H 'Accept: application/json' -d 'title=' | head -n 1

Confirmed by laravel.com

Did this fix it?

Cause 2 of 2

The auth middleware sends guests to the login route

1Check

When the auth middleware sees an unauthenticated user it redirects to the named route login. This applies to your own API route too.

php artisan route:list --path=api
php artisan route:list --name=login

2Fix

The redirect target can be changed with redirectGuestsTo in bootstrap/app.php. For an API that has no login page, send the Accept header and handle the failure on the client instead of redirecting.

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware): void {
    $middleware->redirectGuestsTo('/login');
})

3Verify

Reload config and repeat the call.

php artisan optimize:clear
curl -si http://localhost:8000/api/user -H 'Accept: application/json' | head -n 1

Confirmed by laravel.com

Did this fix it?

How do I stop it coming back?

  • Have every API client add Accept: application/json by default.
  • Test API routes with a JSON header in feature tests, so a redirect is caught early.
  • Keep API routes under routes/api.php and web pages under routes/web.php.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

composer require maatwebsite/excel fails to install

Composer says the package needs an older PHP than the one installed

Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.

3 causes, each with a fix

Back end

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.