API error contract rule | DevPrompt Lab

A repository instruction for implementing predictable API errors that clients can handle safely.

Reusable content

When adding or changing an API, use the repository's existing response envelope. Give errors a stable machine-readable code, an appropriate HTTP status, and a concise user-safe message. Return field errors only for validated input. Never expose stack traces, SQL, secrets, or private record existence. Use the same status and response shape for equivalent failures. Document retryable errors and preserve compatibility with existing clients.

Current error convention: {{CLIENT_CONVENTION}}

Known error cases: {{ERRORS}}

How to use it

Place in the API section of the relevant repository instructions. Replace placeholders with real project conventions.

Example

422 VALIDATION_ERROR with field details; 404 NOT_FOUND for an inaccessible owner-scoped project; 500 INTERNAL_ERROR without database details.