What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Use HTTP status codes to communicate the broad outcome, then return a consistent, machine-readable response body with stable API-specific error details. Clients should branch on codes—not message text—and retry only when the operation is safe to repeat and the failure is documented as transient.
What a consistent API error contract should do
An HTTP status code tells clients the general result of a request. A structured response body can add the specific problem type, a stable error code, and details that help a developer diagnose or correct it. Keep those roles distinct: the body should add detail without changing what the status code means.
As an Amazon Associate I earn from qualifying purchases.
Use error codes as the programmatic contract. Keep them stable as the API evolves, and do not make clients parse human-readable messages to decide what to do. Messages can be useful for developer diagnosis, but wording may change or vary by language. Return only details that are safe for the caller to see; keep sensitive diagnostics in server-side logs.
Choose a response format that fits your API
There is no single body format every API must use. Two documented approaches illustrate the choice: an IETF-defined problem-details format and the response shape specified by Microsoft Graph. Select a contract that suits your ecosystem, document it, and apply it consistently.
#1 Best Overall
- API Design Patterns
- ABIS BOOK
- Manning Publications
| Approach | Structure and purpose | When it fits |
|---|---|---|
| RFC 9457 Problem Details | A common machine-readable format for adding problem-specific detail when an HTTP status alone is not enough. It preserves the status code’s general meaning and obsoletes RFC 7807. | When you want an IETF-defined format that can reduce the need to invent a separate error representation. |
| Microsoft Graph error object | A JSON error object with code and message; optional fields include target, details, and innererror. More specific codes can be nested. |
When implementing Microsoft Graph or a contract designed to follow its guidance. Its shape is Microsoft-specific, not a universal requirement. |
In Microsoft Graph’s guidance, the top-level code is language-independent and maps to the HTTP status description in camel case. Its message is intended for developers, not end users, and the guidance cautions against exposing excessive detail. Treat those conventions as part of that API’s contract rather than assuming other services follow them.
Design the server-side contract
- Inventory existing responses. Check status codes and error bodies across endpoints. Identify inconsistent shapes, codes, and meanings before defining a shared contract.
- Define a common structure and code taxonomy. Give clients stable, machine-readable values to branch on. Keep explanatory prose separate from those values.
- Preserve HTTP semantics. Set the status to match the broad outcome, then use the body for API-specific problem detail. Do not use a body field to redefine the status.
- Document retry behavior. Specify which errors are permanent, transient, or retryable only under certain conditions. Send
Retry-Afterwhen clients should wait before retrying. - Protect side-effecting operations. Where practical, make operations safe to repeat or provide a documented idempotency mechanism.
- Separate public errors from internal diagnostics. Give clients enough information to act without returning secrets, stack traces, or internal state. Record suitable diagnostic detail in server-side logs instead.
- Test the contract. Cover malformed requests, authorization failures, missing resources, throttling, gateway failures, and repeated calls to operations that create side effects.
Handle errors without unsafe retries
First distinguish a caller error from a transient service condition. A malformed request or invalid credentials generally needs a corrected request or credentials, not another identical attempt. A rate limit or temporary service problem may be retryable, but the status alone does not establish that retrying is safe.
Rank #2
Check whether repeating the operation is safe
HTTP method semantics help, but the key question is whether repeating the request can repeat a side effect. Google Cloud’s HTTP guidance treats GET and HEAD as safe retrieval methods; GET, PUT, and DELETE are idempotent, while POST and PATCH are not. Idempotence means repeated requests have the same intended server-side effect; it does not promise identical responses. For example, deleting a resource that no longer exists can return 404 and still be idempotent.
A timeout or gateway error does not prove the server failed to complete the work. Retrying a non-idempotent POST could create a second order or send a second email. Retry an unsafe method only if the API documents a safe-repeat mechanism, or the client can establish that the original request was not applied.
Use status and headers as guidance, not a blanket rule
Microsoft Learn distinguishes several gateway and service failures: 502 means an upstream response was invalid; 503 indicates temporary unavailability and may include Retry-After; and 504 means a gateway timed out without establishing whether upstream work completed. Its guidance recommends retrying 502, 503, and 504 only for idempotent requests, retrying 500 only when the API documents it as safe, and honoring Retry-After.
When a documented transient failure is retryable and there is no Retry-After value, use bounded exponential backoff with random jitter and a finite retry limit. A circuit breaker can help stop repeated requests while failures continue. Do not blindly retry every 5xx or every error response.
Apply rate-limit backoff in context
For HTTP 429 in its Developer Knowledge API context, Google for Developers documents truncated exponential backoff with jitter: min(max_delay, initial_delay * (2 ^ attempt) + jitter). Its example uses a 1-second initial delay, a 32-second cap, and random jitter between 0 and 1 second. These are examples from that service’s guidance, not universal timing requirements; follow the API’s own limits and retry instructions.
Recommended Free Tools
Quick Recap
Check these failure cases in client tests
- Malformed input or invalid credentials: confirm the client surfaces an actionable failure rather than repeating the same request.
- Missing resource: verify status handling does not confuse an expected missing-resource response with a transient outage.
- Throttling: check that the client honors
Retry-Afterwhen supplied and applies a finite policy where documented retries are appropriate. - 502, 503, or 504: test retries only for idempotent requests, accounting for the possibility that upstream work completed before a timeout.
- Side-effecting calls: simulate a lost response and verify that a retry cannot silently create a duplicate effect unless the API provides a safe-repeat mechanism.
- Error body changes: ensure control flow uses stable codes rather than message wording, and that additional safe fields do not break client parsing.
Sources and scope
- IETF RFC 9457: Problem Details for HTTP APIs, July 2023.
- Microsoft Graph: Error responses, maintained guidance.
- Google Cloud: HTTP guidelines, accessed October 7, 2026.
- Microsoft Learn: 500, 502, 503, and 504 errors from APIs, accessed October 7, 2026.
- Google for Developers: Error handling, rate limiting, and quota management, updated October 7, 2026.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
