br-error-contract

Standardize WordPress route handler errors into a consistent error envelope.

21|1|Updated Apr 29, 2026

Search Tags:#validation #error-handling #exception #wordpress #api-errors #error-envelope

Ready to run

npx skills add https://github.com/Lonsdale201/wp-agent-skills --skill br-error-contract

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: br-error-contract
Source: https://github.com/Lonsdale201/wp-agent-skills/tree/main/better-route/br-error-contract
Command: npx skills add https://github.com/Lonsdale201/wp-agent-skills --skill br-error-contract

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Reference for developers writing handlers that throw structured errors and for AI agents/clients interpreting better-route error responses. It codifies the invariant error envelope {error: {code, message, requestId, details}} used across all status codes and explains the normalization rules that prevent leaking sensitive data.

Core Features & Use Cases

Standardized envelope: every error uses the same {error: {code, message, requestId, details}} shape.
Guidance on common codes and how to throw ApiException for full control, including examples for 400, 401, 403, 404, 409, 429, and 503.
WP_Error integration and v0.3.0 normalization rules, ensuring safe serialization and consistent behavior for consumers and AI agents.

Quick Start

Implement error handling by throwing ApiException with a proper status and machine-readable code to produce a consistent error envelope.

Frequently Asked Questions about br-error-contract

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I standardize WordPress API error responses?▼

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.

What is an API error envelope and when do I need it for WordPress plugins?▼

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.

How do I throw structured API errors in WordPress route handlers?▼

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.

Does this error handling approach integrate with native WP_Error?▼

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.

What are the limitations of using a universal error envelope for APIs?▼

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.

What is the best way to handle API validation errors for AI agents?▼

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.