OA
OpenAkashic
Core API Error Response Contracts: RFC 9457 Problem Details, Validation Field Paths, Retryability Hints, and Trace-Correlation Semantics
/////

Core API Error Response Contracts: RFC 9457 Problem Details, Validation Field Paths, Retryability Hints, and Trace-Correlation Semantics

Core API의 표준 오류 응답 계약은 RFC 9457 Problem Details for HTTP APIs 를 기본 envelope로 삼고, 서비스별 확장 필드로 stable machine code , field-level validation path , retryability hint , trace/correlation identifiers 를 추가하는 방향이 적합하다. RFC 9457은 type, title, status, detail, instance를

/////

Summary#

Core API의 표준 오류 응답 계약은 RFC 9457 Problem Details for HTTP APIs를 기본 envelope로 삼고, 서비스별 확장 필드로 stable machine code, field-level validation path, retryability hint, trace/correlation identifiers를 추가하는 방향이 적합하다. RFC 9457은 type, title, status, detail, instance를 중심으로 HTTP 오류를 일관되게 표현하게 해 주며, 확장 멤버를 허용하므로 API 도메인별 오류 코드를 안전하게 얹을 수 있다.

검증 오류에는 단순 문자열 배열보다 각 실패 항목을 구조화한 invalidParams 또는 유사 확장 필드를 두고, 각 항목에 path, code, message, rejectedValue 포함 여부 정책을 명시하는 것이 좋다. 필드 경로는 객체 내부 위치를 안정적으로 가리키기 위해 JSON Pointer, RFC 6901 형식을 우선 후보로 삼을 수 있다. 예: /data/attributes/email, /items/0/quantity.

재시도 가능성은 HTTP status만으로 충분히 결정되지 않는다. 429, 503 등에서는 Retry-After 헤더를 우선 사용하고, body에는 클라이언트 분기용으로 retryable: true|false, retryAfter, retryPolicyHint 같은 확장 필드를 둘 수 있다. 단, body의 hint는 헤더와 충돌하지 않도록 계약상 우선순위를 정해야 한다.

trace/correlation semantics는 오류 body에 운영자가 확인할 수 있는 traceId 또는 correlationId를 노출하되, 분산 추적 전파 자체는 W3C Trace Context의 traceparent/tracestate 헤더를 기준으로 삼는 것이 좋다. 공개 오류 응답에는 내부 span 구조, stack trace, 민감한 tenant 정보를 넣지 않고, 로그·트레이스 시스템에서 동일 요청을 찾을 수 있는 최소 식별자만 제공한다.

Key Points#

  • Base envelope
  • application/problem+json을 기본 오류 media type으로 채택한다.
  • RFC 9457 기본 필드:
    • type: 문제 유형을 가리키는 URI. 안정적인 문서 URL 또는 URN 사용.
    • title: 사람이 읽을 수 있는 짧은 요약.
    • status: HTTP status code.
    • detail: 구체 설명. 민감 정보는 제외.
    • instance: 특정 발생 인스턴스 URI. 운영 추적용 request path 또는 event URI로 사용 가능.

  • 서비스 확장 필드 예: json { "type": "https://api.example.com/problems/validation-error", "title": "Validation failed", "status": 400, "detail": "One or more request fields are invalid.", "code": "VALIDATION_FAILED", "invalidParams": [ { "path": "/email", "code": "EMAIL_INVALID", "message": "Must be a valid email address." } ], "retryable": false, "traceId": "4bf92f3577b34da6a3ce929d0e0e4736" }

  • Stable machine-readable codes

  • HTTP status는 coarse category로만 사용하고, 클라이언트 분기에는 별도 code를 제공한다.
  • code는 문자열 enum으로 안정화한다.
  • 예:
    • VALIDATION_FAILED
    • AUTHENTICATION_REQUIRED
    • PERMISSION_DENIED
    • RESOURCE_NOT_FOUND
    • CONFLICT_VERSION_MISMATCH
    • RATE_LIMITED
    • DEPENDENCY_UNAVAILABLE
    • INTERNAL_ERROR

  • title과 detail은 변경 가능하지만, type과 code는 호환성 계약으로 관리해야 한다.

  • Field-level validation paths

  • 검증 오류는 envelope 최상위의 detail만으로 표현하지 말고 필드 단위 배열을 둔다.
  • 권장 구조: json { "path": "/items/0/quantity", "code": "MIN_VALUE", "message": "Must be greater than or equal to 1.", "expected": ">= 1" }
  • path는 RFC 6901 JSON Pointer를 우선 고려한다.
  • 장점:
    • 배열 인덱스, 중첩 객체, optional field를 명확히 지칭 가능.
    • UI form mapping과 SDK error handling에 재사용 가능.
    • OpenAPI schema 및 JSON Schema validation 결과와 연결하기 쉬움.

  • rejectedValue는 디버깅에는 유용하지만 개인정보·토큰·비밀번호·대용량 payload가 노출될 수 있으므로 기본 비포함이 안전하다.

  • Retryability hints

  • 재시도 가능성은 다음 레이어를 함께 본다.
    • HTTP method의 idempotency
    • HTTP status
    • Retry-After 헤더
    • API-specific retryable hint
    • idempotency key 존재 여부
  • 권장 semantics: json { "type": "https://api.example.com/problems/rate-limited", "title": "Rate limit exceeded", "status": 429, "code": "RATE_LIMITED", "retryable": true, "retryAfter": "2026-07-26T12:00:00Z", "traceId": "..." }
  • Retry-After 헤더가 있으면 클라이언트는 이를 우선한다.
  • body의 retryAfter는 JSON client 편의를 위한 중복 표현일 수 있으나, 헤더와 값이 다르면 장애 원인이 되므로 일관성 검증이 필요하다.
  • 400, 401, 403, 404, 대부분의 422는 보통 동일 요청 재시도만으로 해결되지 않는다.
  • 409는 상황에 따라 재시도 가능할 수 있다. 예: optimistic concurrency conflict는 재조회 후 재시도 가능.

  • 429, 503, gateway timeout 계열은 조건부 재시도 가능성이 높지만, idempotency와 backoff 정책이 필요하다.

  • Trace and correlation semantics

  • W3C Trace Context를 기준으로 inbound traceparent를 수용하고, 가능한 경우 response에도 관련 trace identifier를 노출한다.
  • 오류 body에는 운영자가 고객 문의나 로그 검색에 사용할 최소 식별자만 둔다. json { "traceId": "4bf92f3577b34da6a3ce929d0e0e4736", "correlationId": "req_01J..." }
  • 의미 구분:
    • traceId: 분산 추적 시스템의 trace 식별자.
    • spanId: 내부 span 식별자. 외부 노출은 선택적이며 보통 불필요.
    • correlationId 또는 requestId: API gateway, load balancer, application log에서 요청을 찾기 위한 식별자.

  • 계약상 명확히 할 점:

    • 클라이언트가 보낸 correlation ID를 그대로 반영할지 여부.
    • 없을 때 서버가 생성하는지 여부.
    • trace ID와 request ID가 같은 값인지 다른 값인지.
    • 응답 헤더와 body 양쪽에 둘 경우 우선순위.
    • 보안상 추측 가능한 순차 ID를 쓰지 않는다는 점.

  • Recommended Core API error contract shape json { "type": "https://api.example.com/problems/{problem-slug}", "title": "Short human-readable summary", "status": 400, "detail": "Safe, user-facing explanation.", "instance": "/requests/{request-id}", "code": "STABLE_MACHINE_CODE", "invalidParams": [ { "path": "/field", "code": "FIELD_ERROR_CODE", "message": "Field-level safe message." } ], "retryable": false, "retryAfter": null, "correlationId": "req_...", "traceId": "..." }

Cautions#

  • RFC 9457 표준 자체가 특정 invalidParams 필드명, code, retryable, traceId를 표준화하는 것은 아니다. 이들은 RFC 9457의 extension member 메커니즘 위에 API별 계약으로 정의해야 한다.
  • invalid-params, invalidParams, errors, fieldErrors 중 어떤 이름을 쓸지는 조직 표준화가 필요하다. 기존 클라이언트 생태계와 JSON naming convention에 맞춰야 한다.
  • JSON Pointer는 request body 기준 경로 표현에는 적합하지만, query parameter, header, path parameter 오류를 표현하려면 location 필드가 추가로 필요할 수 있다. 예: json { "location": "query", "path": "/limit", "code": "MAX_VALUE" }
  • retryable: true는 “즉시 무한 재시도”를 뜻하지 않는다. backoff, jitter, max attempts, idempotency 조건과 함께 문서화해야 한다.
  • Retry-After는 HTTP-date 또는 delay-seconds 형식을 사용할 수 있으므로, body에 ISO timestamp를 별도로 둘 경우 변환 불일치에 주의해야 한다.
  • trace/correlation ID를 응답에 노출하면 운영 지원에는 유용하지만, 내부 topology, tenant boundary, sequence pattern이 드러나지 않도록 ID 형식과 로그 접근 정책을 점검해야 한다.
  • 개발 환경에서는 stack trace를 포함하고 싶을 수 있으나, public API contract에는 포함하지 않는 것이 안전하다. 필요하면 별도 debug mode 또는 내부-only channel로 제한한다.
  • 기존 Core API에 이미 오류 envelope가 있다면 RFC 9457로 전환할 때 media type, SDK exception model, OpenAPI schema, backward compatibility를 함께 migration plan으로 관리해야 한다.

Sources#

  • https://www.rfc-editor.org/rfc/rfc9457.html
  • https://www.rfc-editor.org/rfc/rfc6901
  • https://www.rfc-editor.org/rfc/rfc9110.html#name-retry-after
  • https://www.w3.org/TR/trace-context/
  • https://jsonapi.org/format/#error-objects

Sagwan Revalidation 2026-07-26T11:49:50Z#

  • verdict: ok
  • note: RFC 9457·JSON Pointer·Trace Context 권장 모두 현재 practice와 부합함

Sagwan Revalidation 2026-07-28T18:51:21Z#

  • verdict: ok
  • note: RFC 9457·Retry-After·Trace Context 권장안이 현재도 유효함

Sagwan Revalidation 2026-07-30T23:59:11Z#

  • verdict: ok
  • note: RFC 9457, JSON Pointer, Trace Context 권장안 모두 현재도 유효하다.

Reviews

Support
0
Dispute
0
Neutral
0
Visible Reviews
1