Evolve API contracts without losing clients

HTTP 422 · Content-Type: application/problem+json

{
    "type": "https://api.example.net/problems/invalid-window",
    "title": "Invalid time window",
    "status": 422,
    "detail": "The end must follow the start.",
    "instance": "/problems/events/test-17",
    "errors": [
        {
            "field": "end",
            "code": "before-start"
        }
    ]
}

Reading : Body and response statuses agree. The errors array is an extension specific to this example, not a universal standard member.

Test to add : Test the stable before-start code and field association; do not parse detail prose to automate correction.

HTTP 404 · Content-Type: application/problem+json

{
    "title": "Ressource introuvable",
    "instance": "/support/test-18"
}

Reading : The five members are not an all-required checklist. Without a usable type, about:blank applies; the received HTTP status remains 404.

Test to add : Check that the client accepts this minimal response and a localised title without inventing a body status.

HTTP 200 · Content-Type: application/problem+json

{
    "type": "https://api.example.net/problems/access-denied",
    "title": "Access denied",
    "status": 403
}

Reading : Two layers disagree. The advisory JSON status does not replace the status received by generic HTTP clients.

Test to add : Investigate generation and intermediaries; preserve both values rather than declare success from HTTP 200 alone.

HTTP 422 · Content-Type: application/problem+json

{
    "type": 17,
    "title": false,
    "status": "422",
    "detail": [
        "Invalid"
    ],
    "instance": null,
    "traceRef": "test-19"
}

Reading : type, title, status, detail and instance have unexpected types. RFC consumer handling is to ignore them rather than coerce the string "422" into a number.

Test to add : Report the producer defect and test a tolerant client. traceRef remains an extension; about:blank is the default after type is ignored.

HTTP 409 · Content-Type: application/problem+json

{
    "type": "/problems/conflict",
    "title": "Version conflict",
    "status": 409,
    "instance": "?case=test-20",
    "requestRef": "test-20",
    "retryable": false
}

Reading : The type uses a relative path and instance a query reference. This workshop displays them without resolution; the real document base would be required.

Test to add : Define the contract base, prefer an absolute type and test ignored unrecognised extensions. The word retryable alone does not grant universal replay safety.

HTTP 400 · Content-Type: application/problem+json

{
    "type": "https://iana.org/assignments/http-problem-types#date",
    "title": "Date Not Acceptable",
    "status": 400,
    "instance": "/support/test-21"
}

Reading : This type appears in the IANA snapshot. Its recommended status is 400. Comparing only #date or title does not identify the type.

Test to add : Refer the client to this type’s definition in its applicable context; registration does not certify an implementation.

HTTP 503 · Content-Type: application/json

{
    "type": "https://api.example.net/problems/maintenance",
    "title": "Service maintenance",
    "status": 503,
    "detail": "Try the documented recovery path."
}

Reading : The body resembles Problem Details, but the received media-type name is application/json. Structural reading does not verify negotiation or the response contract.

Test to add : Compare Content-Type, documentation and client. This example is not a retry rule: Retry-After and replay safety remain separate checks.

HTTP 400 · Content-Type: application/problem+json

{
    "type": "about:blank",
    "title": "Bad Request",
    "status": 700,
    "instance": "/support/test-22"
}

Reading : status is a JSON number, but 700 lies outside the HTTP three-digit range 100–599. This differs from having the wrong JSON type.

Test to add : Repair generation and preserve the received HTTP status, 400 here. A data-type-only check would have missed this anomaly.