> For the complete documentation index, see [llms.txt](https://docs.opensoutheners.com/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opensoutheners.com/home/laravel-scim/error-handling.md).

# Error Handling

The package automatically formats all errors on SCIM routes as SCIM-compliant JSON per [RFC 7644 Section 3.12](https://datatracker.ietf.org/doc/html/rfc7644#section-3.12).

## Error response format

All errors on SCIM routes return JSON in this format:

```json
{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
    "status": "400",
    "scimType": "invalidValue",
    "detail": "The userName field is required."
}
```

## Automatic error conversion

The package intercepts these exception types on SCIM routes and converts them:

| Exception                 | HTTP Status | scimType       |
| ------------------------- | ----------- | -------------- |
| `ValidationException`     | 400         | `invalidValue` |
| `AuthenticationException` | 401         | -              |
| `HttpException` (404)     | 404         | -              |
| `HttpException` (other)   | varies      | -              |

## Setup with Laravel 11+

If you're using Laravel 11's `bootstrap/app.php` exception handling, register the SCIM error handler:

```php
// bootstrap/app.php
use OpenSoutheners\LaravelScim\Support\SCIM;

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions) {
        SCIM::integrate($exceptions);
    })
    ->create();
```

{% hint style="info" %}
If you're using Laravel 10 with the `ServiceProvider`-based exception handler, the package registers error handling automatically. No extra setup needed.
{% endhint %}

## Throwing SCIM errors manually

Use `ScimErrorException` to throw spec-compliant errors from your custom code:

```php
use OpenSoutheners\LaravelScim\Exceptions\ScimErrorException;
use OpenSoutheners\LaravelScim\Enums\ScimBadRequestErrorType;

throw new ScimErrorException(
    type: ScimBadRequestErrorType::Uniqueness,
    detail: 'A user with this email already exists.',
);
```

### Available error types

| Type             | scimType value  | Description                             |
| ---------------- | --------------- | --------------------------------------- |
| `InvalidFilter`  | `invalidFilter` | Filter syntax is invalid                |
| `TooMany`        | `tooMany`       | Too many results                        |
| `Uniqueness`     | `uniqueness`    | Uniqueness constraint violated          |
| `Mutability`     | `mutability`    | Attempted to modify read-only attribute |
| `InvalidSyntax`  | `invalidSyntax` | Request body is malformed               |
| `InvalidPath`    | `invalidPath`   | Path in PATCH operation is invalid      |
| `NoTarget`       | `noTarget`      | Target resource not found for PATCH     |
| `InvalidValue`   | `invalidValue`  | Value doesn't match expected type       |
| `InvalidVersion` | `invalidVers`   | Version mismatch                        |
| `Sensitive`      | `sensitive`     | Operation on sensitive attribute        |

## Non-SCIM routes

Error formatting only applies to routes with the `scim.v2.*` name prefix. Your regular API and web routes are not affected.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.opensoutheners.com/home/laravel-scim/error-handling.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.