요약 (TL;DR)
RFC 9457 (HTTP API 문제 상세 정보)은 API 오류 응답을 위한 표준 형식입니다. 이 표준은 사용자 지정 오류 형식을 일관된 구조(유형, 제목, 상태, 상세 정보, 인스턴스)로 대체합니다. Modern PetstoreAPI는 적절한 콘텐츠 협상 및 유효성 검사 세부 정보를 통해 모든 오류 응답에 RFC 9457을 구현합니다.
서론
API가 오류를 반환합니다. 이 응답은 어떤 모습인가요? 대부분의 API처럼 여러분만의 형식을 만들었을 것입니다:
{"error": "Invalid email"}
{"message": "Not found", "code": 404}
{"success": false, "errors": ["Email required"]}
모든 API는 다른 오류 형식을 가지고 있습니다. 클라이언트는 각 API마다 사용자 지정 오류 처리가 필요합니다. 오류를 구문 분석하거나 사용자에게 표시하거나 디버깅을 위해 로깅하는 표준적인 방법이 없습니다.
RFC 9457이 이를 해결합니다. 이는 API가 오류를 반환하는 방법을 정의하는 IETF 표준입니다. 여러분만의 형식을 만드는 대신, 클라이언트가 이미 이해하고 있는 검증된 표준을 사용하게 됩니다.
이전 Swagger Petstore는 일관성 없는 사용자 지정 오류 형식을 사용했습니다. Modern PetstoreAPI는 모든 오류 응답에 RFC 9457을 구현하여 구조화되고 기계 판독 가능한 오류 세부 정보를 제공합니다.
이 가이드에서는 RFC 9457이 무엇인지, 올바르게 구현하는 방법, 그리고 Modern PetstoreAPI가 모든 오류 응답에 이를 어떻게 사용하는지 알아봅니다.
API 오류 문제
RFC 9457 이전에는 모든 API가 자체적인 오류 형식을 만들었습니다.
일반적인 오류 형식의 변형
형식 1: 간단한 메시지
{"error": "User not found"}
형식 2: 코드 및 메시지
{"code": "USER_NOT_FOUND", "message": "User not found"}
형식 3: 중첩 구조
{
"success": false,
"error": {
"type": "NotFound",
"message": "User not found"
}
}
형식 4: 오류 배열
{
"errors": [
{"field": "email", "message": "Invalid email"}
]
}
사용자 지정 형식의 문제점
1. 일관성 부족: 클라이언트는 각 API마다 사용자 지정 구문 분석이 필요합니다.
2. 정보 누락: 일부 형식에는 오류 코드가 없거나, 세부 정보가 없거나, 둘 다 없는 경우가 있습니다.
3. 기계 판독 가능한 구조 없음: 오류를 프로그래밍 방식으로 처리하기 어렵습니다.
4. 미흡한 국제화: 오류 메시지가 영어로 하드코딩되어 있습니다.
5. 유효성 검사 오류에 대한 표준 부재: 각 API는 필드 수준 오류를 다르게 처리합니다.
RFC 9457이란?
RFC 9457 (2023년 7월 발행)은 "HTTP API 문제 상세 정보"를 정의합니다. 이는 API가 오류 응답을 구성하는 방법을 명시하는 IETF 표준입니다.
주요 기능
표준 미디어 타입: application/problem+json (또는 application/problem+xml)
일관된 구조: 모든 오류는 동일한 형식을 따릅니다.
기계 판독 가능: 클라이언트가 오류를 프로그래밍 방식으로 구문 분석할 수 있습니다.
확장 가능: 호환성을 유지하면서 사용자 지정 필드를 추가할 수 있습니다.
HTTP 인식: HTTP 상태 코드와 통합됩니다.
RFC 9457 대 사용자 지정 오류
사용자 지정 오류:
{"error": "Email is required"}
RFC 9457 오류:
{
"type": "https://petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains invalid data",
"instance": "/pets",
"errors": [
{
"field": "email",
"message": "Email is required"
}
]
}
RFC 9457 버전은 다음을 제공합니다:
- 문서화를 위한 오류 유형 URL
- 사람이 읽을 수 있는 제목
- HTTP 상태 코드
- 자세한 설명
- 오류를 유발한 요청 경로
- 필드 수준 유효성 검사 세부 정보
RFC 9457 구조 설명
RFC 9457은 다섯 가지 표준 필드를 정의하며 사용자 지정 확장을 허용합니다.
표준 필드
1. type (문자열, 필수)
오류 유형을 식별하는 URI 참조입니다. 사람이 읽을 수 있는 문서화를 가리켜야 합니다.
"type": "https://petstoreapi.com/errors/validation-error"
생략되면 기본값은 about:blank입니다.
2. title (문자열, 필수)
오류 유형에 대한 짧고 사람이 읽을 수 있는 요약입니다. 발생할 때마다 변경되어서는 안 됩니다.
"title": "Validation Error"
3. status (숫자, 필수)
HTTP 상태 코드입니다. 클라이언트가 헤더를 구문 분석할 필요가 없도록 편의를 위해 포함됩니다.
"status": 400
4. detail (문자열, 선택 사항)
이 특정 오류 발생에 대한 사람이 읽을 수 있는 설명입니다.
"detail": "The email field must be a valid email address"
5. instance (문자열, 선택 사항)
오류의 특정 발생을 식별하는 URI 참조입니다. 종종 요청 경로입니다.
"instance": "/pets/019b4132-70aa-764f-b315-e2803d882a24"
사용자 지정 확장
추가 컨텍스트를 위해 사용자 지정 필드를 추가할 수 있습니다:
{
"type": "https://petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"retryAfter": 42,
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:30:00Z"
}
Modern PetstoreAPI가 RFC 9457을 구현하는 방법
Modern PetstoreAPI는 모든 오류 응답에 RFC 9457을 사용합니다.
예시 1: 리소스를 찾을 수 없음
GET /pets/invalid-id
404 Not Found
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/not-found",
"title": "Resource Not Found",
"status": 404,
"detail": "The requested pet does not exist",
"instance": "/pets/invalid-id"
}
예시 2: 인증 오류
GET /pets
401 Unauthorized
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/unauthorized",
"title": "Authentication Required",
"status": 401,
"detail": "Valid authentication credentials are required to access this resource",
"instance": "/pets"
}
예시 3: 요청 한도 초과
GET /pets
429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60
{
"type": "https://docs.petstoreapi.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "You have exceeded the rate limit of 100 requests per minute",
"instance": "/pets",
"limit": 100,
"remaining": 0,
"resetAt": "2026-03-13T10:31:00Z"
}
모든 오류 유형에 대한 Modern PetstoreAPI 오류 처리 문서를 참조하십시오.
RFC 9457을 사용한 유효성 검사 오류
유효성 검사 오류에는 필드 수준 세부 정보가 필요합니다. RFC 9457은 이를 위한 사용자 지정 확장을 허용합니다.
Modern PetstoreAPI 유효성 검사 형식
POST /pets
400 Bad Request
Content-Type: application/problem+json
{
"type": "https://docs.petstoreapi.com/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "The request contains 2 validation errors",
"instance": "/pets",
"errors": [
{
"field": "name",
"message": "Name is required",
"code": "REQUIRED_FIELD"
},
{
"field": "species",
"message": "Species must be one of: DOG, CAT, BIRD, FISH, REPTILE, OTHER",
"code": "INVALID_ENUM_VALUE",
"rejectedValue": "DRAGON"
}
]
}
핵심 사항
errors 배열: 필드 수준 유효성 검사 세부 정보를 포함합니다.
field: 잘못된 필드에 대한 JSON 경로
message: 사람이 읽을 수 있는 오류 메시지
code: 기계 판독 가능한 오류 코드
rejectedValue: 거부된 값 (선택 사항)
이 형식을 통해 클라이언트는 다음을 수행할 수 있습니다:
- 양식에 필드 수준 오류 표시
- 잘못된 필드 강조 표시
- 구체적인 오류 메시지 제공
- 프로그래밍 방식으로 오류 처리
Apidog로 오류 응답 테스트
Apidog는 RFC 9457 준수 여부를 테스트하는 데 도움을 줍니다.
테스트 케이스: 유효성 검사 오류
// Apidog 테스트 스크립트
pm.test("RFC 9457 오류 형식 반환", () => {
const response = pm.response.json();
// 필수 필드 확인
pm.expect(response).to.have.property("type");
pm.expect(response).to.have.property("title");
pm.expect(response).to.have.property("status");
// 상태가 HTTP 상태와 일치하는지 확인
pm.expect(response.status).to.equal(pm.response.code);
// 콘텐츠 유형 확인
pm.expect(pm.response.headers.get("Content-Type"))
.to.include("application/problem+json");
});
pm.test("유효성 검사 오류에 필드 세부 정보 포함", () => {
const response = pm.response.json();
pm.expect(response).to.have.property("errors");
pm.expect(response.errors).to.be.an("array");
response.errors.forEach(error => {
pm.expect(error).to.have.property("field");
pm.expect(error).to.have.property("message");
});
});
테스트 케이스: 오류 유형 URL
pm.test("오류 유형 URL에 접근 가능", async () => {
const response = pm.response.json();
const typeUrl = response.type;
// 유형 URL이 문서화를 반환하는지 확인
const docResponse = await pm.sendRequest(typeUrl);
pm.expect(docResponse.code).to.equal(200);
});
사용자 지정 오류 형식에서 마이그레이션
사용자 지정 오류 형식을 사용하고 있다면, RFC 9457로 마이그레이션하는 방법은 다음과 같습니다.
단계 1: Content-Type 헤더 추가
application/problem+json을 반환하기 시작합니다:
Content-Type: application/problem+json
단계 2: 기존 필드 매핑
사용자 지정 형식을 RFC 9457에 매핑합니다:
이전:
{
"error": "USER_NOT_FOUND",
"message": "User not found"
}
이후:
{
"type": "https://api.example.com/errors/user-not-found",
"title": "User Not Found",
"status": 404,
"detail": "User not found"
}
단계 3: 두 형식 모두 지원 (전환 기간)
콘텐츠 협상을 사용하여 두 형식을 모두 지원합니다:
Accept: application/json → 사용자 지정 형식 반환
Accept: application/problem+json → RFC 9457 형식 반환
단계 4: 사용자 지정 형식 사용 중단
클라이언트가 마이그레이션한 후에는 사용자 지정 형식을 사용 중단하고 기본적으로 RFC 9457을 반환합니다.
결론
RFC 9457은 API 오류 응답을 위한 표준 형식을 제공합니다. 이 표준은 사용자 지정 오류 형식을 클라이언트가 프로그래밍 방식으로 구문 분석할 수 있는 일관되고 기계 판독 가능한 구조로 대체합니다.
Modern PetstoreAPI는 모든 오류 응답에 RFC 9457을 구현하여 적절한 유효성 검사 세부 정보, 오류 유형 URL 및 HTTP 상태 코드를 사용하여 오류를 올바르게 구성하는 방법을 보여줍니다.
Apidog를 사용하여 RFC 9457 준수 여부를 테스트하고, 오류 구조를 검증하며, API가 적절한 오류 응답을 반환하는지 확인하십시오.
자주 묻는 질문
REST API에 RFC 9457이 필수인가요?
필수는 아니지만 권장되는 표준입니다. RFC 9457을 사용하면 API가 더욱 일관되고 클라이언트가 통합하기 쉬워집니다.
RFC 9457을 XML과 함께 사용할 수 있나요?
네, RFC 9457은 JSON (application/problem+json) 및 XML (application/problem+xml) 형식을 모두 정의합니다.
항상 다섯 가지 표준 필드를 모두 포함해야 하나요?
type, title, status는 필수입니다. detail과 instance는 선택 사항이지만 더 나은 오류 컨텍스트를 위해 권장됩니다.
RFC 9457 응답에 사용자 지정 필드를 추가할 수 있나요?
네, RFC 9457은 확장 가능합니다. 추가 컨텍스트를 위해 errors, retryAfter 또는 traceId와 같은 사용자 지정 필드를 추가할 수 있습니다.
RFC 9457로 유효성 검사 오류를 어떻게 처리하나요?
필드 수준 세부 정보가 포함된 사용자 지정 errors 배열을 추가합니다. Modern PetstoreAPI는 유효성 검사 오류 응답에서 이 패턴을 보여줍니다.
오류 유형 URL은 무엇을 가리켜야 하나요?
오류 유형, 가능한 원인 및 해결 방법을 설명하는 사람이 읽을 수 있는 문서를 가리켜야 합니다.
RFC 9457을 사용할 때 HTTP 상태 코드를 변경해야 하나요?
아니요, RFC 9457은 표준 HTTP 상태 코드와 함께 작동합니다. 응답의 status 필드는 HTTP 상태 코드와 일치해야 합니다.
RFC 9457 준수 여부를 어떻게 테스트하나요?
Apidog를 사용하여 오류 응답 구조를 검증하고, 필수 필드를 확인하며, 콘텐츠 유형이 RFC 9457 사양과 일치하는지 확인하십시오.