Copy page

API Reference

Error Handling

Overview

Primebrick uses RFC 7807 Problem Details for HTTP APIs as its universal error format. Every error — from the backend and from every microservice — returns the same JSON structure. This gives clients a single, predictable way to parse and handle errors.

Error response format

Every error response is a JSON object with the following fields:

Field	Type	Required	Description
type	string (URI)	Yes	A stable identifier for the error type
title	string	Yes	A short, human-readable summary
status	number	Yes	The HTTP status code
detail	string	No	A human-readable explanation specific to this occurrence
instance	string	No	The request path that triggered the error
impact	string[]	No	Which UI elements or features are affected (for frontend use)

Example

Code
{
  "type": "https://primebrick.dev/errors/permission-denied",
  "title": "Permission denied",
  "status": 403,
  "detail": "You do not have permission to read customers.",
  "instance": "/api/v1/customers",
  "impact": ["customers-list", "customer-detail"]
}

Stable error codes

The type field is a stable error code in URI form. It does not change between versions for the same error condition. Clients can safely switch on the type value:

Code
switch (error.type) {
  case 'https://primebrick.dev/errors/permission-denied':
    showAccessDeniedBanner();
    break;
  case 'https://primebrick.dev/errors/not-found':
    showNotFoundPage();
    break;
  case 'https://primebrick.dev/errors/validation':
    showValidationErrors(error.detail);
    break;
}

Impact field

The optional impact array tells the frontend which UI elements are affected by the error. This allows the UI to degrade gracefully — disabling or showing an error state only for the affected components rather than showing a global error.

Code
{
  "type": "https://primebrick.dev/errors/service-unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "The billing microservice is currently offline.",
  "instance": "/ws/billing/invoices",
  "impact": ["billing-widget", "invoice-export-button"]
}

The frontend can use this to show a targeted error message on the billing widget while leaving the rest of the page functional.

Common errors

400 — Validation error

Code
{
  "type": "https://primebrick.dev/errors/validation",
  "title": "Validation error",
  "status": 400,
  "detail": "Field 'email' must be a valid email address.",
  "instance": "/api/v1/customers"
}

401 — Unauthorized

Code
{
  "type": "https://primebrick.dev/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required to access this resource.",
  "instance": "/api/v1/customers"
}

403 — Permission denied

Code
{
  "type": "https://primebrick.dev/errors/permission-denied",
  "title": "Permission denied",
  "status": 403,
  "detail": "You do not have permission to delete customers.",
  "instance": "/api/v1/customers/42",
  "impact": ["customer-delete-button"]
}

404 — Not found

Code
{
  "type": "https://primebrick.dev/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "Customer 42 does not exist.",
  "instance": "/api/v1/customers/42"
}

409 — Conflict

Code
{
  "type": "https://primebrick.dev/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A customer with this email already exists.",
  "instance": "/api/v1/customers"
}

503 — Service unavailable

Code
{
  "type": "https://primebrick.dev/errors/service-unavailable",
  "title": "Service unavailable",
  "status": 503,
  "detail": "The billing microservice is currently offline. Please try again later.",
  "instance": "/ws/billing/invoices",
  "impact": ["billing-widget", "invoice-list"]
}

Producing errors in code

The SDK provides a ProblemError helper so services produce compliant errors consistently:

Code
import { ProblemError } from '@primebrick/sdk';

// Simple error
throw new ProblemError({
  type: 'https://primebrick.dev/errors/not-found',
  title: 'Customer not found',
  status: 404,
  detail: `Customer ${id} does not exist.`,
  instance: `/api/v1/customers/${id}`,
});

// With impact (for frontend-aware errors)
throw new ProblemError({
  type: 'https://primebrick.dev/errors/permission-denied',
  title: 'Permission denied',
  status: 403,
  detail: 'You cannot export billing data.',
  instance: '/ws/billing/export',
  impact: ['billing-export-button'],
});

Next steps

• API Overview — base URLs and the OpenAPI spec.
• Microservice Standard — how services produce these errors.
• API Explorer — see errors in action with live requests.