Error Handling

{
  "success": false,
  "message": "Post not found",
  "error": {
    "code": 404,
    "error_code": "NOT_FOUND",
    "timestamp": "2026-10-27T10:30:00+00:00",
    "request_id": "req_6720f1c3a4b5e8.12345678"
  }
}

"error": {
  "code": 500,
  "error_code": "INTERNAL_SERVER_ERROR",
  "timestamp": "...",
  "request_id": "...",
  "exception": "RuntimeException",
  "file": "/app/app/Services/PostService.php",
  "line": 42,
  "trace": [
    { "file": "...", "line": 17, "function": "publish", "class": "App\\Services\\PostService" }
  ]
}

{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "name": ["The name must be at least 2 characters."]
  }
}

use Glueful\Validation\ValidationException;

throw new ValidationException(['email' => ['Email is already taken.']]);
throw ValidationException::forField('email', 'Email is already taken.');
throw ValidationException::forFields(['email' => 'Required.', 'name' => 'Too short.']);
throw ValidationException::withErrors(['email' => 'Required.']); // string values are wrapped in arrays

// A custom envelope message: the third constructor argument
throw new ValidationException(['email' => ['Email is already taken.']], [], 'Could not create the account.');

return Response::error('Payment declined', 402, ['gateway' => 'card_declined']);
// {"success":false,"message":"Payment declined","error":{"code":402,"timestamp":"...","request_id":"...","details":{"gateway":"card_declined"}}}

use Glueful\Bootstrap\ApplicationContext;
use Glueful\Http\Exceptions\Client\ForbiddenException;
use Glueful\Http\Exceptions\Domain\BusinessLogicException;
use App\Models\Post;

final class PostService
{
    public function __construct(private readonly ApplicationContext $context)
    {
    }

    public function publish(string $uuid, string $userUuid): Post
    {
        $post = Post::findOrFail($this->context, $uuid);   // 404 if missing

        if ($post->author_uuid !== $userUuid) {
            throw new ForbiddenException('You can only publish your own posts');
        }

        if ($post->status === 'published') {
            throw BusinessLogicException::invalidState('post', 'published', 'draft'); // 422
        }

        $post->status = 'published';
        $post->save();

        return $post;
    }
}

$e->sqlState();    // ?string, e.g. "23505"
$e->driverCode();  // int|string|null, the vendor code (errorInfo[1])
$e->driver();      // "mysql" | "pgsql" | "sqlite"
$e->getPrevious(); // the original PDOException

{
  "success": false,
  "message": "A conflicting record already exists.",
  "error": { "code": 409, "error_code": "CONFLICT", "timestamp": "...", "request_id": "..." }
}

use Glueful\Database\Exceptions\UniqueConstraintViolationException;
use Glueful\Validation\ValidationException;

try {
    $user = User::create($this->context, ['email' => $email, 'name' => $name]);
} catch (UniqueConstraintViolationException) {
    throw ValidationException::forField('email', 'That email is already registered.');
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later.",
  "retry_after": 42,
  "limit": 60,
  "tier": null
}

HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1793097042
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 1793097042

use Glueful\Http\Exceptions\Contracts\RenderableException;
use Glueful\Http\Response;
use Symfony\Component\HttpFoundation\Request;

final class PaymentDeclinedException extends \RuntimeException implements RenderableException
{
    public function __construct(private readonly string $declineCode)
    {
        parent::__construct('Payment was declined');
    }

    public function render(?Request $request = null): Response
    {
        return new Response([
            'success' => false,
            'message' => $this->getMessage(),
            'error' => ['code' => 402, 'error_code' => 'PAYMENT_DECLINED', 'decline_code' => $this->declineCode],
        ], 402);
    }
}

<?php

namespace App\Providers;

use App\Exceptions\PaymentGatewayTimeout;
use App\Exceptions\QuotaExceeded;
use Glueful\Bootstrap\ApplicationContext;
use Glueful\Database\Exceptions\ForeignKeyConstraintViolationException;
use Glueful\Extensions\ServiceProvider;
use Glueful\Http\Exceptions\Handler;
use Glueful\Http\Response;

final class ExceptionServiceProvider extends ServiceProvider
{
    public function boot(ApplicationContext $context): void
    {
        $handler = app($context, Handler::class);

        $handler
            ->map(ForeignKeyConstraintViolationException::class, 409)
            ->map(PaymentGatewayTimeout::class, 504)
            ->renderable(QuotaExceeded::class, fn (\Throwable $e) => new Response([
                'success' => false,
                'message' => $e->getMessage(),
                'error' => ['code' => 402, 'error_code' => 'QUOTA_EXCEEDED'],
            ], 402))
            ->dontReport(QuotaExceeded::class)
            ->mapChannel(PaymentGatewayTimeout::class, 'payments')
            ->reportUsing(function (\Throwable $e, $request): void {
                // forward to an error tracker
            });
    }
}

// config/serviceproviders.php
return [
    'enabled' => [
        'App\\Providers\\AppServiceProvider',
        'App\\Providers\\ExceptionServiceProvider',
    ],
];

async function api(path, options = {}) {
  const res = await fetch(`/api/v1${path}`, {
    ...options,
    headers: { 'Content-Type': 'application/json', ...options.headers },
  });
  const body = await res.json().catch(() => ({}));
  if (res.ok) return body.data;

  const err = new Error(body.message ?? res.statusText);
  err.status = res.status;
  err.errorCode = body.error?.error_code ?? body.error;   // envelope, or "rate_limit_exceeded"
  err.fields = body.errors ?? body.error?.details ?? {};  // thrown ValidationException, or Response::validation()
  err.requestId = body.error?.request_id;
  err.retryAfter = Number(res.headers.get('Retry-After')) || undefined;
  throw err;
}

use Glueful\Database\Exceptions\UniqueConstraintViolationException;
use Glueful\Http\Exceptions\Client\NotFoundException;
use Glueful\Http\Exceptions\Handler;
use Glueful\Validation\ValidationException;
use PHPUnit\Framework\TestCase;

final class ErrorEnvelopeTest extends TestCase
{
    private function body(\Throwable $e): array
    {
        $response = (new Handler())->setDebug(false)->render($e);
        return json_decode((string) $response->getContent(), true);
    }

    public function test_http_exception_envelope(): void
    {
        $response = (new Handler())->setDebug(false)->render(new NotFoundException('Post not found'));
        $body = json_decode((string) $response->getContent(), true);

        $this->assertSame(404, $response->getStatusCode());
        $this->assertFalse($body['success']);
        $this->assertSame('Post not found', $body['message']);
        $this->assertSame('NOT_FOUND', $body['error']['error_code']);
        $this->assertArrayNotHasKey('trace', $body['error']);
    }

    public function test_validation_uses_top_level_errors(): void
    {
        $body = $this->body(ValidationException::forField('email', 'Required.'));

        $this->assertSame(['email' => ['Required.']], $body['errors']);
        $this->assertArrayNotHasKey('error', $body);
    }

    public function test_unique_violation_is_409(): void
    {
        $pdo = new \PDOException('duplicate key');
        $pdo->errorInfo = ['23505', 7, 'duplicate key'];

        $body = $this->body(UniqueConstraintViolationException::fromPdo($pdo, 'pgsql'));

        $this->assertSame('CONFLICT', $body['error']['error_code']);
        $this->assertSame('A conflicting record already exists.', $body['message']);
    }
}