RESTful API
design & development
in Fremont

Every API fails sometimes. What matters is what the caller learns when it does. A bare status code with an empty body leaves the developer guessing, and guessing turns into support tickets.

Start with status codes used consistently. A malformed request is a client error. A missing record is a not found. A conflict, such as creating something that already exists, has its own code. Server errors should mean the fault is on the provider side, and nothing else. When codes are used loosely, integrators cannot write sensible retry logic.

The body should follow one shape everywhere. A machine readable error code, a short human message, and a pointer to the field that caused it. Some teams adopt the problem details format described in an internet standard. Others define their own. Consistency is what counts.

Validation errors deserve extra care. If a request has three bad fields, return all three at once, each with its own code and message, so the caller can show every problem to its user in a single pass. Returning them one by one forces three round trips and a frustrated user filling in the same form again and again.

Error codes are part of the contract. Once published, a code such as insufficient_balance should keep its meaning for as long as the API version lives, because integrators branch their logic on it. Messages can be reworded freely. Codes cannot.

Tell the caller whether trying again makes sense. A timeout or a temporary outage is worth retrying after a pause, and a header with the suggested wait makes that explicit. A rejected card or a missing permission will fail the same way every time, so the response should make clear that a retry is pointless and a change is needed on the caller side.

Business rule failures need the same care as technical ones. When an order cannot be cancelled because it has already shipped, the error should say exactly that, with a code the integrator can map to a message in its own interface, instead of a generic complaint about an invalid request.

Include a request ID in every response, successful or not. When an integrator writes to support, that ID lets the provider find the exact log line in seconds. Without it, the conversation starts with timestamps and guesswork.

Be careful with detail. Stack traces, SQL fragments and internal hostnames do not belong in a public response. They help attackers more than developers. Log them on the server and return a clean message.

Finally, document every error an endpoint can return, with an example body. Most integration time is spent on the unhappy paths.