Run a mock round

Group them by intent and be consistent:

• 2xx success: 200 OK, 201 Created (with Location), 202 Accepted for async work, 204 No Content after DELETE.
• 3xx: 301/308 for permanent redirects, 304 Not Modified for conditional GET.
• 4xx client errors: 400 malformed syntax, 401 unauthenticated, 403 forbidden, 404 not found, 405 wrong method, 409 conflict, 412 precondition failed, 415 unsupported media type, 422 semantic validation failure, 429 rate limited.
• 5xx server errors: 500 unexpected failure, 502 bad gateway, 503 unavailable (include Retry-After), 504 gateway timeout.

Do not return 200 with an error body: it breaks monitoring, retries and generic clients. Reserve 5xx for genuine server faults so alerts stay meaningful. Pick 400 for malformed requests but 422 for well-formed input that fails business validation, and document your mapping.

REST excels at resource-oriented CRUD with cacheable, uniform interfaces and a broad tool ecosystem. It becomes awkward when:

• The domain is action-oriented or RPC-like, such as "recalculate rating" or complex algorithms where resource nouns feel forced.
• Clients need many different projections and REST forces over-fetching or many round trips; GraphQL lets the client shape the response.
• You need low-latency, strongly typed, bi-directional streaming between internal services; gRPC with HTTP/2 and protobuf is a better fit.
• You need real-time push; WebSockets or server-sent events are required since REST is request-response.
• You must perform large batches or long-running jobs synchronously.

The alternative is not always all-or-nothing. Many systems expose a REST or GraphQL edge to clients and use gRPC or messaging internally. Choose based on consumers, latency, payload shape and how naturally the domain maps to resources.

401 Unauthorized means the request lacks valid authentication credentials. The client should authenticate and retry, and the response should include a WWW-Authenticate header describing the scheme.

403 Forbidden means the server understood the request and knows who the caller is, but the caller is not allowed to perform it. Re-authenticating will not help; the identity simply lacks permission.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"

Practical mapping: a missing or expired token gives 401, while a valid token with an insufficient role gives 403. For sensitive resources, many APIs return 404 instead of 403 so attackers cannot learn whether a resource exists. Avoid returning 400 for permission failures, because it hides the real cause from clients and monitoring.

Do not hold the connection open. Instead accept the work and return 202 Accepted with a pointer to a status resource.

POST /reports
Location: /reports/jobs/789
Retry-After: 5

HTTP/1.1 202 Accepted
{ "id": "789", "status": "running", "progress": 0.4 }

The client polls the job URL, or you notify it via a webhook or server-sent events. When finished, the status resource either includes the result or links to it, and the job may transition to succeeded or failed with error details. Store jobs durably so a server restart does not lose them, and let polling use conditional requests and Retry-After to reduce load.

Design for idempotency: a retried POST should return the same job rather than starting a second one. Also give jobs a retention policy so the status store does not grow without bound, and consider cancellation endpoints for user-initiated work.

• POST creates a subordinate resource or triggers a non-idempotent action. The server assigns the identifier and returns 201 with a Location header.
• PUT replaces the entire resource at a known URI and is idempotent. Any omitted field is reset, which surprises clients doing partial updates.
• PATCH applies a partial modification and is generally not idempotent unless the patch document is written to be so.

PATCH /users/42
Content-Type: application/merge-patch+json

{ "email": "new@example.com" }

Two PATCH formats dominate: JSON Merge Patch (RFC 7396, simple) and JSON Patch (RFC 6902, a list of explicit operations). Prefer PUT when the client owns the full representation, PATCH when it does not. A frequent pitfall is using PUT with a partial body, which silently wipes unspecified fields.

Two main approaches:

• Offset pagination: GET /items?limit=20&offset=40. Simple and allows jumping to a page, but degrades as offsets grow because the database must scan and discard rows, and results shift when items are inserted or deleted.
• Cursor (keyset) pagination: GET /items?limit=20&after=eyJpZCI6MTIzfQ. The cursor encodes the last seen sort key, so the query uses an indexed range scan and stays stable under concurrent writes.

SELECT * FROM items
WHERE (created_at, id) < (:last_created, :last_id)
ORDER BY created_at DESC, id DESC
LIMIT 20;

Use cursor pagination for feeds and large, changing datasets; offset only for small admin tables. Always cap the limit, return a next link or cursor, avoid exposing raw IDs when they leak information, and document the sort order because cursors are only valid for it.

The client generates a unique key per logical operation and sends it in a header, typically Idempotency-Key.

POST /payments
Idempotency-Key: 4d7c2e6a-2b1f-4f9a-9c3d-1a2b3c4d5e6f

{ "amount": 5000, "currency": "USD" }

The server stores the key together with the request fingerprint and the final response (or a "processing" marker). On a retry with the same key it returns the stored response instead of charging again. Use a unique constraint on the key to make concurrent duplicates safe: one request wins and others receive 409 while the first is in flight.

Keys should expire after a sensible window, be scoped per account, and detect mismatched payloads by comparing a hash. This pattern is essential for payments, order creation and any non-idempotent POST that clients or gateways may retry.

Use one consistent, machine-readable shape. A widely adopted choice is RFC 7807 application/problem+json:

{
  "type": "https://example.com/problems/insufficient-funds",
  "title": "Insufficient funds",
  "status": 422,
  "detail": "Account balance is 10 USD, required 50 USD.",
  "instance": "/payments/abc",
  "errors": [
    { "field": "amount", "code": "above_balance" }
  ]
}

Key properties: a stable type or code clients can branch on, a human-readable message, the HTTP status mirrored in the body, and field-level details for validation errors. Never leak stack traces, SQL or internal hostnames. Include a correlation or request id so support can trace the failure in logs.

Design the error contract once and reuse it across every endpoint; inconsistent error shapes are one of the most common sources of brittle client code.

An operation is idempotent when performing it multiple times produces the same server state as performing it once.

• GET, HEAD, PUT and DELETE are idempotent by HTTP semantics.
• POST is not idempotent; repeated calls may create multiple resources.
• PATCH is not guaranteed to be idempotent.

PUT /users/42/email

Idempotency matters for retries: a client or gateway can safely retry an idempotent request after a timeout. For non-idempotent operations such as payments, use an idempotency key so the server can detect and deduplicate retries. Note that idempotency refers to server side effects, not the response code: the same DELETE may return 204 the first time and 404 the second, yet the end state is unchanged.