application/problem

API Design

Meaning

The media type identifier for RFC 7807 Problem Details, used in HTTP headers to signal that a response body is a structured JSON document describing an API error. It addresses the pain point of inconsistent, unstructured error responses across REST APIs by giving clients a predictable schema to parse. It is reached for whenever an HTTP API needs to return machine-readable error information instead of plain text or ad-hoc JSON shapes.

Primary Function

API error format

Communicative Purpose

Standardizes machine-readable error reporting in HTTP APIs so clients can parse failure details consistently across services.

Pattern

HTTP header: Content-Type: application/problem+json (server response) | Accept: application/problem+json (client request)

Função primária

API error format

Propósito comunicativo

Standardizes machine-readable error reporting in HTTP APIs so clients can parse failure details consistently across services.

Situações de gatilho

REST API design: returning structured error details with HTTP 4xx/5xx status codes HTTP API consumption: client sets Accept header to request problem+json responses API documentation: specifying error response content types in OpenAPI specs

Contextos

REST APIs, HTTP, OpenAPI/Swagger, microservices, web service backends

Padrão

HTTP header: Content-Type: application/problem+json (server response) | Accept: application/problem+json (client request)

Colocados típicos

Content-Type header
Accept header
RFC 7807
Problem Details
HTTP status codes
JSON response body

Substituições comuns

application/json with custom error schema: flexible but non-standard
requires per-API docs text/plain error messages: human-readable but unparseable by clients application/xml error responses: legacy SOAP-style
heavier than JSON

Erros comuns

Using application/json instead of application/problem+json: loses the standardized signal that the body follows RFC 7807 Omitting required RFC 7807 fields (type, title, status): breaks client parsers that expect the schema Returning problem+json with a 2xx status code: contradicts the convention that problem documents accompany error codes Forgetting to advertise it in the Accept header: clients may not know they can request structured errors

Similar / contraste

application/json: generic JSON container, not specifically for errors text/html error pages: browser-rendered, not machine-parseable application/vnd.api+json: JSON:API spec media type, for resource documents not errors

Interferências

Coming from generic web development: may default to application/json for every response — application/problem+json specifically signals RFC 7807 Problem Details and should only be used for error bodies

Família do chunk

HTTP content types
RFC 7807 Problem Details
API error handling patterns
Content-Type negotiation

Nuance

When NOT to use: non-HTTP transports (gRPC, message queues), or trivial APIs where plain text suffices Performance: zero runtime cost beyond the header string; the body schema is the actual payload Boundary conditions: the response body must conform to RFC 7807 members (type, title, status, detail, instance) or the media type promise is broken

Efeito pragmático

Lets API clients write one error-handling code path that works across many services, reducing per-API integration cost and enabling generic tooling like API gateways and error dashboards.

Dica de memória

Think of application/problem+json as a stamped envelope: the stamp tells the client 'open me with your RFC 7807 parser' instead of guessing what shape the error takes.

Upgrade path

RFC 7807 Problem Details full schema: type (URI), title, status, detail, instance, plus extensions

Frequência: MediumFormulaicidade: Fully fixedPrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

from flask import Flask, jsonify app = Flask(__name__) @app.errorhandler(404) def not_found(error): response = jsonify({ "type": "/errors/not-found", "title": "Resource not found", "status": 404, "detail": "The requested URL was not found on the server.", "instance": "/api/users/42" }) response.headers["Content-Type"] = "application/problem+json" return response, 404

import requests response = requests.get( "https://api.example.com/orders/999", headers={"Accept": "application/problem+json"} ) if response.status_code >= 400: problem = response.json() print(f"{problem['status']}: {problem['title']} — {problem['detail']}")

// Express.js middleware that always emits problem+json for errors app.use((err, req, res, next) => { res.status(err.status || 500); res.type("application/problem+json"); res.json({ type: `/errors/${err.code || "internal"}`, title: err.message, status: res.statusCode, instance: req.originalUrl }); });