API error handling: telling a client what went wrong and what to do

Most integration time is spent on failures, not on the happy path — and most of that time is spent guessing. API error handling decides whether a developer reads your response and knows what to do, or opens a support ticket because "it returns 500 sometimes". The useful question when designing one is not what went wrong but what the caller should do next.

The distinction that matters most

Split every failure into two groups: the caller can fix it, or they cannot. A malformed request, a missing field, an invalid identifier — those are the caller's to fix, and retrying unchanged will fail identically forever. A timeout, a dependency outage, a rate limit — those are transient, and retrying is the correct behaviour. If your response does not let a client tell these apart, every integration either retries things that will never succeed or gives up on things that would have worked on the second attempt.

What an error body should contain

• A stable machine-readable code that does not change when you reword the message. Clients branch on this.
• A human message written for the developer reading logs, not for an end user.
• The field or parameter at fault, where the error is about input.
• Whether the request may be retried, and after how long — this removes the guessing entirely.
• A request identifier the caller can quote in a support conversation, which turns an unreproducible report into a lookup.
• Nothing sensitive. Error bodies end up in logs, screenshots and tickets.

Keep the error shape identical across every endpoint, including the ones added later. A client writes one error handler; a second shape means that handler silently fails to parse exactly when something has already gone wrong.

Choosing status codes

1. Use 400 for malformed input and 422 where the request is well-formed but semantically wrong, if you draw that distinction — then draw it consistently.
2. Use 401 for missing or invalid credentials and 403 where the credential is valid but not permitted. Conflating them sends people to the wrong fix.
3. Use 404 for a resource that does not exist, not for a path you did not implement.
4. Use 409 for conflicts, which is what a duplicate idempotency key with a different body should return.
5. Reserve 5xx for your faults. Returning 500 for a validation error teaches clients to retry something that cannot succeed.

Design API error handling before the feature

Error cases designed at the end become whatever the framework produced by default, which is how stack traces reach production and how one endpoint answers in a shape nothing else uses. Listing the failure modes while designing the endpoint takes ten minutes and usually improves the success path too — several of them turn out to be avoidable by changing the input rather than by reporting a failure.

The Ettex Api documents the authentication model and the endpoint catalogue in one place, and the same error contract applies to every endpoint it exposes. Where retries are involved, the error body and idempotency work together: the first tells a client it may retry, the second makes the retry safe.