HTTP Errors

Package: @opra/common

OPRA provides a hierarchy of typed HTTP error classes. Throw any of these from an operation handler or interceptor — adapters catch them and serialize the response automatically.

---

Class hierarchy

Error
└── OpraException
    └── OpraHttpError
        ├── BadRequestError          (400)
        ├── UnauthorizedError        (401)
        ├── ForbiddenError           (403)
        │   └── PermissionError      (403)
        ├── NotFoundError            (404)
        ├── MethodNotAllowedError    (405)
        ├── NotAcceptableError       (406)
        ├── ConflictError            (409)
        │   └── ResourceConflictError (409)
        ├── UnprocessableEntityError (422)
        │   └── ResourceNotAvailableError (422)
        ├── FailedDependencyError    (424)
        └── InternalServerError      (500)

---

OpraException

Base class for all OPRA exceptions.

import { OpraException } from '@opra/common';

throw new OpraException('Something went wrong');
throw new OpraException({ message: 'Invalid input', code: 'INVALID_INPUT' });
throw new OpraException('Upstream failed', causeError);

Properties

Property	Type	Description
message	string	Human-readable error message.
severity	'error' | 'warning' | 'fatal'	Defaults to 'error'.
code	string | undefined	Machine-readable error code.
system	string | undefined	Originating subsystem identifier.
details	any	Arbitrary additional details.
cause	Error | undefined	The underlying cause, if any.

Constructor

new OpraException(issue: string | Partial<ErrorIssue> | Error, cause?: Error)

---

OpraHttpError

Extends OpraException with an HTTP status code. All HTTP-specific errors inherit from this class.

import { OpraHttpError } from '@opra/common';

throw new OpraHttpError('Service unavailable', 503);
throw new OpraHttpError({ message: 'Rate limit exceeded', code: 'RATE_LIMIT' }, 429);

Additional properties

Property	Type	Description
status	number	HTTP status code.

Methods

Method	Description
setStatus(code)	Overrides the status code. Returns this for chaining.

---

HTTP error classes

Each error class sets a fixed status and a default message and code. All accept an optional string | Partial<ErrorIssue> argument to customize the message or code, and an optional cause Error.

throw new NotFoundError();
throw new NotFoundError('Customer not found');
throw new NotFoundError({ message: 'Customer not found', code: 'CUSTOMER_NOT_FOUND' });

Class	Status	Default code	Default message
BadRequestError	400	BAD_REQUEST	'Bad request'
UnauthorizedError	401	UNAUTHORIZED	"You don't have permission to perform this action"
ForbiddenError	403	FORBIDDEN	'You are not authorized to perform this action'
PermissionError	403	PERMISSION_ERROR	'You dont have permission for this operation'
NotFoundError	404	NOT_FOUND	'Not found'
MethodNotAllowedError	405	METHOD_NOT_ALLOWED	'Method not allowed'
NotAcceptableError	406	NOT_ACCEPTABLE	'Not Acceptable'
ConflictError	409	CONFLICT	'Conflict'
UnprocessableEntityError	422	UNPROCESSABLE_ENTITY	'Unprocessable entity'
FailedDependencyError	424	FAILED_DEPENDENCY	'The request failed due to failure of a previous request'
InternalServerError	500	INTERNAL_SERVER_ERROR	'Internal server error'

---

Specialized errors

ResourceConflictError

Status 409. Use when a resource already exists with the same unique field values.

import { ResourceConflictError } from '@opra/common';

throw new ResourceConflictError('Customer', ['email']);
throw new ResourceConflictError('Customer', ['email', 'tenantId'], cause);

new ResourceConflictError(resource: string, fields: string | string[], cause?: Error)

Parameter	Type	Description
resource	string	Name of the conflicting resource.
fields	string | string[]	Field name(s) that caused the conflict.
cause	Error	Optional underlying error.

ResourceNotAvailableError

Status 422. Use when a referenced resource exists in the system but is not accessible in the current context.

import { ResourceNotAvailableError } from '@opra/common';

throw new ResourceNotAvailableError('Order', orderId);
throw new ResourceNotAvailableError('Product', productId, cause);

new ResourceNotAvailableError(resource: string, keyValue?: any, cause?: Error)

---

ErrorIssue interface

The ErrorIssue interface describes the shape of an error's serialized form and is accepted as the constructor argument for all error classes.

interface ErrorIssue {
  message: string;
  severity: 'error' | 'warning' | 'fatal';
  system?: string;
  code?: string;
  details?: any;
  diagnostics?: string | string[];
  stack?: string;
}

toJSON() on any OpraException returns this shape (stack is included only in development/test environments).