Feature Guide

A quick orientation block that answers the essential questions: what this feature does, how it works, why it matters, and the key concepts behind it.

What this does

Structured Errors demonstrates that Semitexa API failures stay machine-readable even when the route throws domain exceptions.

How it works

The route throws typed domain exceptions, and ExternalApiExceptionMapper turns them into one JSON envelope with a stable `error.code`, human message, structured context, and optional retry metadata.

Why it matters

API clients need more than a string message. A stable envelope lets SDKs, dashboards, and background jobs branch on error semantics without scraping text.

Key concepts

ExternalApiExceptionMapper: Maps domain exceptions on external API routes into stable JSON error envelopes.
error.context: Structured machine-readable metadata that explains the failure without parsing the message.
request_id: Correlation id slot for tracing a failing API request across logs and support channels.

Route GET /demo/api/structured-errors?type=not-found

Response 404 application/json

CLI curl -H "Accept: application/json" "http://localhost:9502/demo/api/structured-errors?type=not-found"

Header	Value
`Content-Type`	`application/json`

Machine-readable error body

{
    "error": {
        "code": "not_found",
        "message": "Demo API product #missing-product not found.",
        "context": {
            "resource": "Demo API product",
            "identifier": "missing-product"
        },
        "request_id": null,
        "docs_url": null
    }
}

DomainException

Verified against Semitexa Ultimate 2026.09.19.1020

Structured Errors

API failures should stay operationally useful. The ExternalApiExceptionMapper intercepts any DomainException thrown from an #[ExternalApi] route and transforms it into a predictable JSON error envelope before the response leaves the framework.

How it works

Domain exceptions carry typed context — field errors for validation failures, retry_after for rate limits, resource identifiers for not-found cases. The mapper reads that context and places it under error.context in the response body. The HTTP status code maps directly from the exception type. The outer envelope shape is always { error: { code, message, context, request_id, docs_url } }.

Why this matters

Clients can rely on error structure even when the business path fails. Validation problems stay nested under error.context.fields, auth failures keep the same outer shape with only the status changing, and retry guidance appears in both the Retry-After header and the machine-readable body. SDKs and dashboards can branch on error.code with one parser instead of two.

1<?php23declare(strict_types=1);45namespace App\Application\Handler\Api;67use App\Application\Exception\Api\DemoApiNotFoundException;8use App\Application\Payload\Api\ApiErrorTriggerPayload;9use App\Application\Resource\Api\ErrorEnvelopeResource;10use Semitexa\Core\Attribute\AsPayloadHandler;11use Semitexa\Core\Contract\TypedHandlerInterface;1213#[AsPayloadHandler(payload: ApiErrorTriggerPayload::class, resource: ErrorEnvelopeResource::class)]14final class ApiErrorTriggerHandler implements TypedHandlerInterface15{16    public function handle(ApiErrorTriggerPayload $payload, ErrorEnvelopeResource $resource): ErrorEnvelopeResource17    {18        throw new DemoApiNotFoundException('Product', 'demo-product');19    }20}21

<?php

declare(strict_types=1);

namespace App\Application\Handler\Api;

use App\Application\Exception\Api\DemoApiNotFoundException;
use App\Application\Payload\Api\ApiErrorTriggerPayload;
use App\Application\Resource\Api\ErrorEnvelopeResource;
use Semitexa\Core\Attribute\AsPayloadHandler;
use Semitexa\Core\Contract\TypedHandlerInterface;

#[AsPayloadHandler(payload: ApiErrorTriggerPayload::class, resource: ErrorEnvelopeResource::class)]
final class ApiErrorTriggerHandler implements TypedHandlerInterface
{
    public function handle(ApiErrorTriggerPayload $payload, ErrorEnvelopeResource $resource): ErrorEnvelopeResource
    {
        throw new DemoApiNotFoundException('Product', 'demo-product');
    }
}

1<?php23declare(strict_types=1);45namespace App\Application\Payload\Api;67use App\Application\Resource\Api\ErrorEnvelopeResource;8use Semitexa\Api\Attribute\ExternalApi;9use Semitexa\Core\Attribute\AsPublicPayload;1011#[ExternalApi]12#[AsPublicPayload(13    path: '/api/demo/errors/{scenario}',14    methods: ['GET'],15    responseWith: ErrorEnvelopeResource::class,16    produces: ['application/json'],17)]18final class ApiErrorTriggerPayload19{20    protected string $scenario = 'not-found';2122    public function setScenario(string $scenario): void23    {24        $this->scenario = $scenario;25    }26}27

<?php

declare(strict_types=1);

namespace App\Application\Payload\Api;

use App\Application\Resource\Api\ErrorEnvelopeResource;
use Semitexa\Api\Attribute\ExternalApi;
use Semitexa\Core\Attribute\AsPublicPayload;

#[ExternalApi]
#[AsPublicPayload(
    path: '/api/demo/errors/{scenario}',
    methods: ['GET'],
    responseWith: ErrorEnvelopeResource::class,
    produces: ['application/json'],
)]
final class ApiErrorTriggerPayload
{
    protected string $scenario = 'not-found';

    public function setScenario(string $scenario): void
    {
        $this->scenario = $scenario;
    }
}

1<?php23declare(strict_types=1);45namespace App\Application\Api;67use Throwable;89final class ExternalApiExceptionMapper10{11    public function toEnvelope(Throwable $exception): array12    {13        return [14            'error' => [15                'type' => 'not_found',16                'message' => $exception->getMessage(),17            ],18        ];19    }20}21

<?php

declare(strict_types=1);

namespace App\Application\Api;

use Throwable;

final class ExternalApiExceptionMapper
{
    public function toEnvelope(Throwable $exception): array
    {
        return [
            'error' => [
                'type' => 'not_found',
                'message' => $exception->getMessage(),
            ],
        ];
    }
}

1<?php23declare(strict_types=1);45namespace App\Application\Exception\Api;67final class DemoApiNotFoundException extends \RuntimeException8{9    public function __construct(string $resource, string $id)10    {11        parent::__construct(sprintf('%s "%s" was not found.', $resource, $id));12    }13}14

<?php

declare(strict_types=1);

namespace App\Application\Exception\Api;

final class DemoApiNotFoundException extends \RuntimeException
{
    public function __construct(string $resource, string $id)
    {
        parent::__construct(sprintf('%s "%s" was not found.', $resource, $id));
    }
}

Envelope Notes

What this endpoint is proving

Concern	Behavior	Why it matters
Exception mapping	A typed domain exception becomes `{ error: { code, message, context, request_id } }`.	Clients can rely on error structure even when the business path fails.
Context preservation	Resource name and identifier stay in `error.context` instead of being buried in text.	Support tooling can diagnose failures without brittle string parsing.

How it works

The route throws typed domain exceptions, and ExternalApiExceptionMapper turns them into one JSON envelope with a stable `error.code`, human message, structured context, and optional retry metadata.

Why it matters

API clients need more than a string message. A stable envelope lets SDKs, dashboards, and background jobs branch on error semantics without scraping text.

Key concepts

ExternalApiExceptionMapper: Maps domain exceptions on external API routes into stable JSON error envelopes.
error.context: Structured machine-readable metadata that explains the failure without parsing the message.
request_id: Correlation id slot for tracing a failing API request across logs and support channels.

Find a concept, task, or command

Structured Errors

What this does

How it works

Why it matters

Key concepts

Not-found envelope

Structured Errors

How it works

Why this matters

What this endpoint is proving

How it works

Why it matters

Key concepts