Error handling | laravel-openapi-cli | Spatie

 SPATIE

  Laravel OpenAPI CLI
======================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-openapi-cli](https://spatie.be/docs/laravel-openapi-cli/v1)  Advanced-usage  Error handling

 Version   v1

 Other versions for crawler [v1](https://spatie.be/docs/laravel-openapi-cli/v1)

- [ Introduction ](https://spatie.be/docs/laravel-openapi-cli/v1/introduction)
- [ Support us ](https://spatie.be/docs/laravel-openapi-cli/v1/support-us)
- [ Installation & setup ](https://spatie.be/docs/laravel-openapi-cli/v1/installation-setup)
- [ Questions and issues ](https://spatie.be/docs/laravel-openapi-cli/v1/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-openapi-cli/v1/changelog)
- [ About us ](https://spatie.be/docs/laravel-openapi-cli/v1/about-us)

Basic usage
-----------

- [ Registering an API ](https://spatie.be/docs/laravel-openapi-cli/v1/basic-usage/registering-an-api)
- [ Command naming ](https://spatie.be/docs/laravel-openapi-cli/v1/basic-usage/command-naming)
- [ Path & query parameters ](https://spatie.be/docs/laravel-openapi-cli/v1/basic-usage/path-and-query-parameters)
- [ Sending data ](https://spatie.be/docs/laravel-openapi-cli/v1/basic-usage/sending-data)
- [ Listing endpoints ](https://spatie.be/docs/laravel-openapi-cli/v1/basic-usage/listing-endpoints)
- [ Authentication ](https://spatie.be/docs/laravel-openapi-cli/v1/basic-usage/authentication)
- [ Output formatting ](https://spatie.be/docs/laravel-openapi-cli/v1/basic-usage/output-formatting)

Advanced usage
--------------

- [ Error handling ](https://spatie.be/docs/laravel-openapi-cli/v1/advanced-usage/error-handling)
- [ Multiple APIs ](https://spatie.be/docs/laravel-openapi-cli/v1/advanced-usage/multiple-apis)
- [ Debugging ](https://spatie.be/docs/laravel-openapi-cli/v1/advanced-usage/debugging)
- [ Command reference ](https://spatie.be/docs/laravel-openapi-cli/v1/advanced-usage/command-reference)

 Error handling
==============

###  On this page

1. [ Default error handling ](#content-default-error-handling)
2. [ Custom error handling ](#content-custom-error-handling)
3. [ Redirect handling ](#content-redirect-handling)

Default error handling
--------------------------------------------------------------------------------------------------------------------------

- **4xx/5xx errors**: Displays the status code and response body in human-readable format by default (or JSON with `--json`, minified with `--minify`). HTML responses suppress the body by default (use `--output-html` to see it). Other non-JSON responses show the raw body with a content-type notice.
- **Network errors**: Shows connection failure details.
- **Missing path parameters**: Tells you which `--option` is required.
- **Invalid JSON input**: Shows the parse error.

All error cases exit with a non-zero code for scripting.

Custom error handling
-----------------------------------------------------------------------------------------------------------------------

Register an `onError` callback to handle HTTP errors in a way that's specific to your API:

```
OpenApiCli::register(base_path('openapi/api.yaml'), 'api')
    ->baseUrl('https://api.example.com')
    ->bearer(env('API_TOKEN'))
    ->onError(function (Response $response, Command $command) {
        return match ($response->status()) {
            403 => $command->error('Your API token lacks permission for this endpoint.'),
            429 => $command->warn('Rate limited. Try again in ' . $response->header('Retry-After') . 's.'),
            500 => $command->error('Server error — try again later.'),
            default => false, // fall through to default handling
        };
    });
```

The callback receives the `Illuminate\Http\Client\Response` and the `Illuminate\Console\Command` instance, giving you access to all Artisan output methods (`line()`, `info()`, `warn()`, `error()`, `table()`, `newLine()`, etc.).

Return a truthy value to indicate "handled" — this suppresses the default "HTTP {code} Error" output. Return `false` or `null` to fall through to default error handling. The command always exits with a non-zero code regardless of whether the callback handles the error.

Redirect handling
-----------------------------------------------------------------------------------------------------------

By default, HTTP redirects are **not followed**. This means a `301` or `302` response is returned as-is, so you can see exactly what the API responds with. To opt in to following redirects:

```
OpenApiCli::register(base_path('openapi/api.yaml'), 'api')
    ->baseUrl('https://api.example.com')
    ->followRedirects();
```