Public API Error Message Review

# Public API Error Message Review

A public API error is product copy. For an indie product, it may be the only support interaction a developer sees before deciding whether the product is reliable. Error messages do not need to be verbose, but they must say what failed, whether retrying helps, and what field or condition caused the problem.

## Required fields
A useful API error should include a stable code, a human-readable message, and a target when the failure is tied to a field or object. The HTTP status tells the broad category; it does not explain the fix. “400 Bad Request” is not enough. “local_slug is required” is better. “local_slug must be lowercase letters, numbers, or hyphens” is better still.

## Retry guidance
Errors should distinguish permanent failures from temporary failures. Validation errors should not invite retries. Rate limits should include a retry window if possible. Server errors should avoid exposing internals but still acknowledge that the client may retry later.

## Consistency check
Review whether similar endpoints use the same words for the same idea. If one endpoint says workspace_id and another says project_id for the same object, integration code becomes harder to debug. Naming inconsistency is a support cost.

## Example shape
{ code: "invalid_slug", message: "local_slug must use letters, numbers, or hyphens", field: "local_slug" }

## Practical review
Before announcing an API, intentionally send three bad requests: missing required field, invalid enum, and duplicate object. If those responses do not tell a new developer what to fix, the endpoint is not ready as a public growth surface.

Public API Error Message Review

// COMMENTS

ON THIS PAGE