arkyn
ChangelogGuides
docs / bad-responses / conflict

Conflict

The Conflict class represents an HTTP error response with status code 409. It is used to standardize "Conflict" error responses, typically when a request conflicts with the current state of a resource.

Import

ts

import { Conflict } from "@arkyn/server/conflict";
Learn how subpath and root imports differ in How do I use imports.

Constructor

  • message (required): A descriptive message explaining the conflict cause.
  • cause (optional): Additional information about the conflict cause, which can be any serializable data.

Methods

toResponse() - Converts the instance into a Response object with JSON body and Content-Type: application/json header.
toJson() - Alternative method using Response.json() for generating the JSON error response.

Usage example

typescript

import { Conflict } from "@arkyn/server/conflict";


// Basic usage - throw the error
throw new Conflict("Email already registered");


// With cause information
throw new Conflict("Resource version mismatch", {
    currentVersion: 5,
    requestedVersion: 3,
});


// Convert to Response object
const error = new Conflict("Username already taken");
return error.toResponse();


// Using toJson alternative
return error.toJson();

Response structure

The response body follows a standardized structure:

json

{
    "name": "Conflict",
    "message": "Email already registered"
}
This is sent with HTTP status 409, set on the Response object itself, the status code is not part of the JSON body.
If a cause is passed to the constructor, it is included in the body as well:

json

{
    "name": "Conflict",
    "message": "Resource version mismatch",
    "cause": "{\"currentVersion\":5,\"requestedVersion\":3}"
}

Notes

When thrown, this class automatically emits a debug log to the console showing the file and function where the error originated. See DebugService to configure ignored files for accurate caller detection.
The cause parameter, when provided, is serialized with JSON.stringify() and included in the response body under the cause key, it is sent to clients, not just kept for server-side debugging. Because it's stringified, cause appears in the JSON body as a JSON-encoded string rather than a nested object.
Common use cases include duplicate entries, version conflicts, concurrent modification errors, and resource state conflicts.
Related in Bad responses
On this page
    arkyn