- HTTP status code
- response headers
- error code
- retryability signal
- cache signal
- correlation signal
- deprecation signal
- security signal
- compatibility signal

- client retry yang salah
- workflow salah cabang
- duplicate order
- false alert
- bad customer-facing error
- lost observability
- broken generated client
- backward compatibility break
- API gateway policy mismatch

Status code is just a wrapper around JSON response.

Status code is the first machine-readable classification of the result.

2xx -> request succeeded at HTTP/API boundary
3xx -> caller may need redirection/cache-aware handling
4xx -> caller/client/request problem
5xx -> server/dependency/system problem

- retry decision
- SDK/generated client behavior
- API gateway behavior
- circuit breaker metrics
- alerting
- synthetic monitoring
- client error handling
- UI message mapping
- workflow continuation

Case A: validation error -> 400
Case B: validation error -> 422
Case C: validation error -> 200 with { success: false }
Case D: validation error -> 500 because exception leaked

- client harus menangani banyak bentuk error
- generated client tidak bisa dipercaya
- monitoring tidak akurat
- alert 5xx bisa noisy
- business error bercampur dengan technical error

Success
Client/request problem
Authentication/authorization problem
Conflict/state problem
Not found/visibility problem
Rate limit/quota problem
Dependency/system problem
Temporary overload

GET /quotes/Q-1001 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json

- GET resource detail
- search/list result
- command endpoint yang sengaja mengembalikan resource/result detail

{
  "success": false,
  "error": "QUOTE_EXPIRED"
}

HTTP/1.1 200 OK

POST /quotes HTTP/1.1

HTTP/1.1 201 Created
Location: /quotes/Q-1001
Content-Type: application/json

return Response
    .created(uriInfo.getAbsolutePathBuilder().path(quoteId).build())
    .entity(response)
    .build();

Apakah operasi benar-benar membuat resource baru?
Apakah resource punya identifier stabil?
Apakah Location header menunjuk URI canonical?

- async quote validation
- async pricing calculation
- order submission yang diproses workflow
- downstream orchestration
- long-running job

HTTP/1.1 202 Accepted
Location: /operations/op-123
Retry-After: 5
Content-Type: application/json

{
  "operationId": "op-123",
  "status": "ACCEPTED",
  "statusUrl": "/operations/op-123"
}

202 means accepted for processing, not completed.

Client treats 202 as business success.
UI shows order complete while backend has not completed downstream orchestration.

Is there a status resource or callback/event contract for completion?

- DELETE success
- update command with no response body
- idempotent state transition with no representation returned

HTTP/1.1 204 No Content
Content-Type: application/json

{"status":"deleted"}

- API gateway
- ingress
- load balancer
- CDN
- auth gateway

HTTP client tidak follow redirect.
Authorization header hilang saat redirect.
POST berubah menjadi GET karena redirect handling buruk.
Signed request invalid karena host/path berubah.

- Apakah API service pernah mengembalikan 3xx sendiri?
- Apakah redirect dilakukan di gateway?
- Apakah internal HTTP client follow redirect?
- Apakah Authorization header dipertahankan saat redirect?

- invalid JSON
- invalid query parameter type
- missing required parameter
- invalid enum value at API boundary
- malformed date

- MessageBodyReader gagal deserialize JSON
- ParamConverter gagal convert query/path parameter
- Bean Validation gagal pada request DTO, jika strategy internal memakai 400

Apakah error ini request-shape error, bukan domain-state error?

401 = caller belum terautentikasi atau token tidak valid.

- missing token
- invalid token
- expired token
- invalid signature
- invalid issuer/audience when treated as authentication failure

WWW-Authenticate: Bearer

Cek apakah auth gateway atau service sendiri yang menghasilkan 401.

- user authenticated but lacks quote:approve
- service identity valid but not allowed to submit order
- tenant valid but resource not accessible under policy

401 = who are you?
403 = you are known, but not allowed.

GET /quotes/Q-unknown

Not found because ID does not exist?
Not found because wrong tenant?
Not found because user lacks permission?
Not found because route mismatch?

client response: 404 NOT_FOUND
internal log reason: RESOURCE_NOT_FOUND | TENANT_MISMATCH | POLICY_HIDDEN

POST /quotes/Q-1001

@GET
@Path("/quotes/{id}")

- Apakah JAX-RS runtime mengembalikan 405 otomatis?
- Apakah gateway mengubah 405 menjadi 404?
- Apakah OPTIONS/preflight diperlakukan benar?

Accept: application/xml

@Produces(MediaType.APPLICATION_JSON)

Client library default Accept header tidak sesuai.
Endpoint lupa @Produces.
Provider XML/JSON tidak terdaftar.

- quote already approved cannot be edited
- order already submitted cannot be cancelled through this endpoint
- optimistic locking version mismatch
- duplicate idempotency conflict
- state transition conflict

400 = request malformed/invalid at boundary
409 = request understandable but conflicts with current state

PUT /quotes/Q-1001
If-Match: "v7"

HTTP/1.1 412 Precondition Failed

Apakah API memakai ETag/If-Match atau version field di body?

Content-Type: text/plain

@Consumes(MediaType.APPLICATION_JSON)

Client lupa Content-Type.
Multipart endpoint tidak register provider.
Gateway mengubah Content-Type.

- JSON valid
- DTO valid secara shape
- tetapi business validation gagal

Quote line has incompatible product combination.
Pricing effective date is outside valid catalog window.

Pilih satu policy internal dan konsisten.

- Apakah internal API guideline membedakan 400 vs 422?
- Apakah generated client dan error mapper mendukung 422?

Retry-After: 30
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1720000000

Client retry immediately -> thundering herd.
Server returns 500 instead of 429 -> false incident classification.

- alerting
- SLO/error budget
- retry policy
- circuit breaker
- incident triage

Any exception -> 500

ValidationException -> 400/422
AuthException -> 401/403
NotFoundException -> 404
StateConflictException -> 409
OptimisticLockException -> 409/412
DownstreamTimeoutException -> 504/503 depending boundary
UnexpectedNullPointerException -> 500

Apakah 502 berasal dari service, ingress, load balancer, API gateway, atau service mesh?

- overload/load shedding
- dependency critical unavailable
- maintenance
- circuit open and no fallback

Retry-After: 10

503 tanpa Retry-After membuat client retry aggressive.

Timeout terjadi di mana?
- client -> gateway
- gateway -> service
- service -> DB
- service -> downstream API
- service -> Kafka/queue

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "errorCode": "QUOTE_ALREADY_APPROVED",
  "message": "Quote cannot be modified after approval.",
  "correlationId": "01J...",
  "details": {
    "quoteId": "Q-1001",
    "currentState": "APPROVED"
  }
}

HTTP status = coarse protocol-level classification
errorCode   = stable business/technical classification
message     = human-readable explanation
correlation = operational traceability

{
  "message": "Oops quote already approved"
}

{
  "errorCode": "QUOTE_ALREADY_APPROVED",
  "message": "Quote cannot be modified after approval."
}

- content negotiation
- cache behavior
- correlation/tracing
- authentication/authorization
- idempotency
- concurrency control
- pagination/linking
- rate limiting
- deprecation/versioning
- security hardening
- gateway/proxy behavior

Content-Type: application/json
Accept: application/json
Content-Length: 1234
Content-Encoding: gzip

- Request with body should send Content-Type.
- Response with body should send Content-Type.
- Accept should influence representation selection.
- Compression may be handled by service, gateway, or proxy.

@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)

@Produces does not guarantee gateway will preserve headers unchanged.

- Are content headers set by JAX-RS, servlet container, gateway, or platform?
- Are default media types defined internally?

X-Correlation-ID: 01JABC...
X-Request-ID: req-123
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
tracestate: vendor=value

Trace ID       -> distributed tracing graph
Span ID        -> one operation within trace
Correlation ID -> application/log search identifier
Causation ID   -> why this operation happened, often command/event lineage

A request crosses HTTP -> Kafka -> worker, but correlation headers are not propagated.
Logs cannot connect API call to event consumer.

Does this endpoint read, create, validate, and propagate correlation context?

POST /orders HTTP/1.1
Idempotency-Key: 01JABC...

- first request stores key + result
- duplicate request with same key returns same result or conflict
- same key with different payload should be rejected

201 Created -> first successful creation
200 OK      -> duplicate request returns previous result
409 Conflict -> key reused for different semantic request
425/429/503 -> depending platform and policy

- Is Idempotency-Key supported?
- Is it required for POST order submit?
- Where is key stored: DB, Redis, gateway?
- What is key TTL?

ETag: "v7"
If-Match: "v7"
If-None-Match: "v7"
Last-Modified: Wed, 10 Jul 2026 10:00:00 GMT
If-Modified-Since: Wed, 10 Jul 2026 10:00:00 GMT

- optimistic concurrency control
- cache validation
- lost update prevention

PUT /quotes/Q-1001
If-Match: "v7"

HTTP/1.1 412 Precondition Failed

{
  "quoteId": "Q-1001",
  "version": 7,
  "changes": {}
}

- Does internal API use ETag or body version field?
- Is optimistic locking exposed to clients?
- Are stale updates rejected deterministically?

Link: </quotes?cursor=abc>; rel="next"
X-Total-Count: 1402

{
  "items": [],
  "pageInfo": {
    "nextCursor": "abc",
    "hasMore": true
  }
}

Body metadata is often easier for generated clients.
Link headers align with web standards.
Choose and standardize.

- Where does pagination metadata live?
- Are total counts allowed or too expensive?
- Is cursor opaque?

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1720000000
Retry-After: 30

- Are rate limits enforced by gateway, service, Redis, or platform?
- Are headers standardized?
- Are tenant-specific limits possible?
- Are internal service-to-service calls rate limited?

Service returns 429 but does not tell client when to retry.
Client retries immediately.
Rate limiter becomes part of outage amplification.

Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: </docs/api-migration>; rel="deprecation"

- endpoint deprecation
- field deprecation
- old API version retirement
- migration communication

- docs
- consumer inventory
- monitoring of usage
- migration window
- support process

- Does the organization use Deprecation/Sunset headers?
- Is there an API deprecation policy?
- Are deprecated endpoints monitored by consumer?

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
Content-Security-Policy: default-src 'none'
Referrer-Policy: no-referrer

- Are security headers required at service layer or gateway layer?
- Are APIs browser-accessible?
- Does CORS policy exist?
- Are headers overwritten by ingress/API gateway?

@GET
@Path("/{quoteId}")
@Produces(MediaType.APPLICATION_JSON)
public Response getQuote(@PathParam("quoteId") String quoteId) {
    QuoteResponse response = quoteService.getQuote(quoteId);
    return Response.ok(response).build();
}

@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Response createQuote(CreateQuoteRequest request, @Context UriInfo uriInfo) {
    QuoteResponse created = quoteService.createQuote(request);

    URI location = uriInfo
        .getAbsolutePathBuilder()
        .path(created.quoteId())
        .build();

    return Response
        .created(location)
        .entity(created)
        .header("X-Correlation-ID", Correlation.currentId())
        .build();
}

@POST
@Path("/{quoteId}/pricing-runs")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public Response startPricing(
        @PathParam("quoteId") String quoteId,
        PricingRunRequest request,
        @Context UriInfo uriInfo
) {
    OperationResponse operation = pricingService.startPricing(quoteId, request);

    URI location = uriInfo
        .getBaseUriBuilder()
        .path("operations")
        .path(operation.operationId())
        .build();

    return Response
        .accepted(operation)
        .location(location)
        .header("Retry-After", "5")
        .build();
}

@DELETE
@Path("/{quoteId}")
public Response deleteQuote(@PathParam("quoteId") String quoteId) {
    quoteService.deleteDraftQuote(quoteId);
    return Response.noContent().build();
}

throw new RuntimeException("Quote expired");

public final class QuoteExpiredException extends DomainException {
    public QuoteExpiredException(String quoteId) {
        super("QUOTE_EXPIRED", "Quote has expired", quoteId);
    }
}

@Provider
public class DomainExceptionMapper implements ExceptionMapper<DomainException> {
    @Override
    public Response toResponse(DomainException exception) {
        ErrorResponse body = ErrorResponse.from(exception, Correlation.currentId());

        return Response
            .status(mapStatus(exception))
            .type(MediaType.APPLICATION_JSON)
            .entity(body)
            .build();
    }
}

QUOTE_EXPIRED              -> 409 Conflict or 422 depending policy
QUOTE_NOT_FOUND            -> 404 Not Found
QUOTE_ALREADY_APPROVED     -> 409 Conflict
VALIDATION_FAILED          -> 400 or 422 depending policy
AUTHENTICATION_FAILED      -> 401 Unauthorized
PERMISSION_DENIED          -> 403 Forbidden
DOWNSTREAM_TIMEOUT         -> 504 Gateway Timeout or 503 depending boundary
UNEXPECTED_ERROR           -> 500 Internal Server Error

HTTP/1.1 200 OK

{
  "success": false,
  "error": "ORDER_FAILED"
}

- monitoring sees success
- client retry logic breaks
- generated clients cannot classify error
- API semantics are lost

- client errors page operators
- SLO becomes noisy
- domain conflicts look like outage
- real 500 becomes harder to detect

X-Trace
X-TraceId
X-Request-Trace
X-Correlation
CorrelationId

Use platform standard consistently.
Prefer W3C trace context where tracing is involved.

First POST /orders -> 201 Created
Duplicate retry    -> 409 Conflict

Same idempotency key + same payload -> return previous successful result.
Same idempotency key + different payload -> 409 Conflict.

{
  "message": "org.postgresql.util.PSQLException: deadlock detected"
}

{
  "errorCode": "TEMPORARY_DATABASE_CONFLICT",
  "message": "The request could not be completed due to a temporary conflict.",
  "correlationId": "01J..."
}

1. What did the resource method return?
2. Did ExceptionMapper transform the response?
3. Did filter/interceptor add/remove headers?
4. Did Servlet container modify response?
5. Did gateway/ingress/API management modify status or headers?
6. Did client library reinterpret response?
7. Did generated client map status incorrectly?

- access logs
- application logs with correlation ID
- JAX-RS filter logs
- gateway logs
- distributed trace
- raw curl output
- OpenAPI contract
- integration test

curl -i \
  -H 'Accept: application/json' \
  -H 'X-Correlation-ID: debug-123' \
  https://example.internal/quotes/Q-1001

Status code
- Is success status semantically correct?
- Are create/update/delete/async cases distinguished?
- Are validation/domain/technical errors mapped correctly?
- Are retryable vs non-retryable errors clear?

Headers
- Is Content-Type correct?
- Is Location present for 201 when applicable?
- Is Retry-After present for 429/503/202 polling when applicable?
- Are correlation/trace headers propagated?
- Are ETag/If-Match headers used or intentionally not used?
- Are deprecation/version headers needed?

Compatibility
- Does OpenAPI reflect status codes and headers?
- Do generated clients handle these statuses?
- Are new errors additive and documented?
- Is behavior consistent with existing endpoints?

Observability
- Are status/error metrics meaningful?
- Is error code logged?
- Is correlation ID present in response/log/trace?

Security
- Are 401/403/404 choices deliberate?
- Are sensitive details hidden from response?
- Are security headers handled by service or gateway?

API governance
- Is there an internal HTTP/API style guide?
- Is there an official status code matrix?
- Is 400 vs 422 standardized?
- Is 409 vs 412 standardized?
- Is async command expected to return 202?

Headers
- Which correlation/request/trace headers are standard?
- Is W3C trace context used?
- Are custom X-* headers allowed?
- Are Location, Retry-After, ETag, Deprecation, Sunset used?

Gateway/platform
- Which headers are added/removed by gateway?
- Does gateway normalize errors?
- Does ingress/API gateway rewrite status codes?
- Are CORS/security headers service-owned or gateway-owned?

JAX-RS implementation
- Which ExceptionMappers exist?
- Which filters add headers?
- Are status codes manually built or centralized?
- Are response envelopes standardized?

Testing/governance
- Are status codes represented in OpenAPI?
- Is API linting enforced in CI?
- Are generated clients used?
- Are contract tests checking headers/status?

Operations
- Which status codes count against SLO?
- Are 4xx/5xx dashboards separated?
- Are 409/422 monitored for product/business issues?

If the caller can fix the request -> probably 4xx.
If the system/dependency failed -> probably 5xx.
If the operation was accepted but not completed -> 202.
If a new resource was created -> 201 + Location.
If current resource state prevents operation -> 409.
If conditional header/version failed -> 412.
If request body shape is invalid -> 400.
If semantic validation failed -> 400 or 422 depending policy.
If authenticated but not permitted -> 403.
If not authenticated -> 401.
If throttled -> 429 + Retry-After.
If temporarily unavailable -> 503 + Retry-After.

- HTTP status is semantically correct
- headers carry useful machine-readable metadata
- errors are classified consistently
- retry behavior is safe
- correlation is preserved
- security information is not leaked
- OpenAPI reflects actual behavior
- gateway/service responsibility is explicit