Api Problem Laravel Package

Product Decisions This Supports

• Standardizing the public error contract before an API launch. RFC 9457 (formerly 7807) application/problem+json is the interoperable shape for API errors. Adopting it is a contract decision that outlives any framework choice, so it belongs in the API style guide, not in a sprint.
• Build vs. buy on the error envelope. This package is the "buy" answer for the data model (type, title, status, detail, instance, plus extension members). It replaces a bespoke {error: {code, message}} shape that every team reinvents and every client SDK must special-case.
• Error taxonomy as a product surface. The type URI is a stable, documented identifier per error class. That gives you a versionable catalog of failure modes you can map to help-docs pages, support macros, and SDK exception classes — directly reducing "what does this error mean?" tickets.
• Multi-service and multi-language roadmap. Because the format is spec-defined rather than Laravel-defined, mobile, partner, and non-PHP services consume one shape. This is the deciding input when scoping whether a second backend service can share an SDK.
• Deprecation and migration signalling. Extension members carry machine-readable remediation data (limits, retry hints, field-level validation errors) so you can change behavior without breaking parsers.
• Prioritizing platform work. If the roadmap includes partner integrations or a paid API tier, error-format consistency is a prerequisite; if the surface is a single internal admin API, it is not worth the cycle.
• Observability and incident triage. Consistent type/instance values make error dashboards and alert routing tractable instead of string-matching free-text messages.

When to Consider This Package

Adopt when:

• You are exposing an API to external consumers, partners, or multiple first-party clients, and error shape is part of the contract.
• You already use (or will use) PSR-7/PSR-17 messages, or you are willing to write a thin Laravel adapter (~50–100 LOC) mapping HttpProblemException to Illuminate\Http\JsonResponse in the exception handler.
• You want typed value objects and named subclasses (NotFound, Unauthorized, ValidationFailed-style 4xx/5xx) rather than raw arrays, so error construction is compile-time checked and testable.
• You want a small, MIT-licensed, framework-agnostic dependency with no runtime coupling to Laravel's internals.

Look elsewhere when:

• The API is internal-only and Laravel's default JSON exception rendering is already adequate — the ceremony will not pay back.
• You need batteries-included behavior: automatic mapping of ValidationException, AuthenticationException, ModelNotFoundException, and ThrottleRequestsException; or automatic Retry-After / WWW-Authenticate header handling. This library sets status and content type only — header semantics and framework exception translation are your adapter's job.
• You need hypermedia (JSON:API, HAL) or OpenAPI generation from code. Use spec-first tooling or a fuller API framework; this is a data model, not a documentation generator.
• You need localized, user-facing messages. The library carries whatever strings you give it; copy strategy remains a product decision.
• Your organization requires a commercially supported or high-adoption dependency. At 249 stars and near-zero dependent packages, you are an early adopter: vendor risk is low (small codebase, MIT, trivially forkable, spec-anchored so switching costs are bounded) but support risk is on you.

How to Pitch It (Stakeholders)

To executives: One standard error format across our APIs. It shortens partner onboarding, cuts integration support tickets, and makes error responses self-describing so clients can react programmatically instead of parsing prose. Cost is low and reversible: a small MIT-licensed library plus a week of engineering to wire into the exception layer; the specification is public, so we are not locked in.

To engineering: RFC 9457-compliant typed value objects with named HTTP-status subclasses, an exception type implementing Throwable, arbitrary extension members for things like validation details and trace IDs, and a PSR-7 response factory that emits application/problem+json. Framework-agnostic by design; in Laravel we register renderables in the exception handler and produce a JsonResponse. Known gap: response headers (Retry-After, WWW-Authenticate) and framework exception mapping are ours to implement — budget for that explicitly rather than assuming it is included.