Errors are part of the developer experience
Errors shape how fast developers can recover from failure. A vague message wastes time and creates support tickets.
A structured error response turns a failure into a clear action: fix a field, refresh a token, retry later.
Define one error schema
Pick a standard shape and use it everywhere. A minimal schema includes a stable code, a human message, and optional details.
Consistency makes client libraries easier to build and reduces the need for special cases.
Use stable error codes
Human messages can change, but error codes should be stable. Clients can use codes to decide whether to retry or show a specific prompt.
Keep codes short, descriptive, and documented.
Field-level validation
When a payload is invalid, return field-level errors. This lets clients highlight the exact input that needs fixing.
A typical format is `errors: [{ field: 'email', message: 'invalid' }]`.
Do not leak internal details
Never expose stack traces or internal exceptions. They can reveal vulnerabilities and confuse API consumers.
Log internal errors server-side with a correlation ID, then return a safe, friendly message.
Handle partial failures explicitly
Batch operations can partially succeed. Return a status that reflects partial success and include per-item results.
That lets clients retry only failed items instead of the entire batch.
Document your error catalog
A short catalog of codes and fixes saves time. It reduces support load and improves client quality.
The best error documentation is small, specific, and consistent.