br-error-contract

Standardize WordPress API error responses by enforcing a universal error envelope using the shape {error: {code, message, requestId, details}} across all status codes. This ensures consistent behavior for clients and AI agents consuming your API routes.

An API error envelope is a standardized JSON structure that wraps all error responses uniformly. You need it for WordPress plugins to prevent leaking sensitive data and to provide AI agents with predictable, machine-readable error details.

Throw structured API errors in WordPress route handlers by using ApiException with a proper HTTP status and machine-readable code. This produces a consistent error envelope, giving you full control over error details for statuses like 400, 401, and 503.

Yes, this error handling approach integrates with native WP_Error. It applies v0.3.0 normalization rules to ensure safe serialization and consistent behavior when mapping common WordPress error codes into the universal API error envelope.

A limitation of using a universal error envelope is that strict normalization rules may restrict custom error formats. You must adhere to the specified {error: {code, message, requestId, details}} shape, which requires refactoring non-standard WordPress error handling.

The best way to handle API validation errors for AI agents is to return a standardized error envelope with machine-readable codes and validation shapes. This allows consuming AI clients to reliably interpret error responses and take corrective actions.