문제: 서버 쪽 상한이 찬 거절이 전송마다 다른 코드였다. web-advanced는 ADMISSION_REFUSED(503), fileserver는 instance·전송 pool 포화까지 TRANSFER_ADMISSION_REJECTED(429 RATE_LIMIT), gRPC는 RATE_LIMIT_EXCEEDED (RESOURCE_EXHAUSTED, "요청이 너무 잦습니다")였다. client는 자기 빈도 탓인지 서버 포화인지 가를 수 없었다. web은 상태만 아는 모든 503을 REQUEST_TIMEOUT으로 답했다 (§4는 비동기 시간 초과만). §4에 OPERATION_NOT_FOUND가 없었고, fileserver 오류 code 27개 중 23개가 계약 문서에 없었으며 예시가 "data": null을 실었다. fileserver는 Retry-After를 발생만 보고 붙여, 본문이 retryable=false로 좁힌 code에도 헤더가 나갔다. gRPC Javadoc과 graphql 스냅숏 머리말이 지운 이름(WORKLOG_NOT_FOUND, spi)을 적었다. 고른 방법(리뷰 README 6절 ②): - 공용 OperationalError.SERVER_BUSY(503, TRANSIENT_DEPENDENCY, retryable, Retry-After 1)를 더했다. registry 행, RetryAfterAdvisor, runbook server-busy.md를 같이 둔다. - web-advanced admission 거절, gRPC call admission(UNAVAILABLE), fileserver의 instance permit·직접 다운로드 permit·전송 pool 포화가 이 코드다. fileserver는 같은 이름의 FileserverErrorCode.SERVER_BUSY를 두고, 이름이 같은 code의 뜻이 같은지 FileserverExceptionTest가 이미 본다. 호출자 자기 scope의 동시 전송 초과만 TRANSFER_ADMISSION_REJECTED 429로 남는다. - 상태만 아는 503은 SERVER_BUSY, AsyncRequestTimeoutException만 REQUEST_TIMEOUT이다(HttpStatusErrorCodes.forException). - fileserver Retry-After는 본문과 같은 규칙(code와 발생이 모두 retryable)으로 붙인다. 재시도 불가 code인 ATOMIC_PUBLISH_UNSUPPORTED를 표에서 뺐다. - docs/fileserver/http-contract.md에 오류 code 표 전체를 두고 예시의 data:null을 지웠다. http-contract §4에 OPERATION_NOT_FOUND와 SERVER_BUSY를 적었다. - decisions 2.3에 결정 ①②③ 행을 더했다. - 포화 시험의 sleep(200)을 첫 거절 신호로 바꾸고, timeout 시험이 code까지 본다(같은 파일이라 RR9-03-20의 그 부분을 여기서 고친다). - web-advanced 파일의 spotless 정리(앞 커밋분)를 함께 싣는다. 버린 대안: JOB_EXECUTOR_REJECTED를 재사용 — 백그라운드 job 이름이라 요청 허가 거절을 읽는 client와 runbook을 잘못 이끈다. 위험·한계: 포화 거절로 분기하던 client와 재시도 정책, WebAdvancedError .ADMISSION_REFUSED를 참조하던 코드, 모든 503을 REQUEST_TIMEOUT으로 보던 client가 바뀐다(upgrade 안내 8·9·13). BREAKING CHANGE: 서버 포화 코드가 SERVER_BUSY 하나다(web-advanced ADMISSION_REFUSED 삭제, fileserver instance·pool 포화 429 → 503, gRPC RESOURCE_EXHAUSTED → UNAVAILABLE). 상태만 아는 503은 SERVER_BUSY다. 할 일은 docs/upgrade/2026-11-round9-contracts.md. Refs: RR9-03-06, RR9-03-07, RR9-03-11, RR9-03-12, RR9-03-15, RR9-03-16, RR9-03-20
19 KiB
HTTP wire 계약
이 백엔드의 HTTP 응답을 읽는 클라이언트(짝 프론트, 파생 서비스의 다른 앱)가 기대해도 되는 것을 한
곳에 적는다. 응답 모양과 멱등성 응답의 뜻은 이 문서가 정본이다. 다른 문서(web README 예외 표,
docs/web/runbook.md, docs/registries/error-codes.yaml 주석)는 이 문서를 가리키고 같은 문장을 쓴다.
코드가 이 문서를 지키는지는 다음 테스트가 확인한다.
- 응답 원문의 키 집합:
src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/envelope/EnvelopeWireShapeTest.java - 핸들러 밖 오류(
/error디스패치)의 실패 Envelope: 실제 컨테이너에서WebContractAssertions(TomcatWebContractIT·Jetty lane), 기본 JWT 체인에서JwtChainErrorDispatchIT - 멱등성 응답의 status·code·retryable·
Retry-After:IdempotencyExceptionMappingTest,RetryAfterAdvisorTest,OperationalErrorTest, 키 형식은IdempotencyKeyHeaderTest, 실행 전 거부와 결과 불명의 구분은IdempotencyExecutorTest, lease 하한은IdempotencySettingsTest - 헤더 규칙(3절):
WebMvcRequestIdFilterTest,CorsSecurityFilterIntegrationTest - web 전용 코드(4절):
TransportErrorHandlingTest,IdempotencyKeyHeaderTest, web-advancedWebAdvancedErrorMappingTest
1. Envelope 키 존재 규칙
JSON 응답은 모두 Envelope 하나의 모양이다(소유자 결정 2). 값이 null인 필드는 키째 생략한다.
빈 목록([])은 null이 아니므로 생략하지 않는다.
| 응답 | 최상위 키 | 없는 키 |
|---|---|---|
| 성공 | success(=true), data, meta |
error |
| 실패 | success(=false), error, meta |
data |
| bulk 전체 성공 | success(=true), results, meta |
error |
| bulk 부분 실패 | success(=false), error(code=BATCH_PARTIAL_FAILURE, details=항목별 결과), meta |
results |
success가 판별자다. 클라이언트는success로 갈라 읽고, 키가 있는지로 판단하지 않는다.- 성공인데
data가null이면data키도 없다. 본문이 아예 없는 응답(204)은 Envelope가 아니다. - 컨트롤러가
String을 반환해도 JSON을 요청하면(Accept: application/json) 같은 Envelope로 나간다 ("data": "<문자열>"). 텍스트를 요청하면 문자열 그대로다. - 빈 컬렉션 결과는
"data": [], 빈 bulk 결과는"results": [], 항목 없는 부분 실패는"details": []로 나간다.
error 키
| 키 | 항상 있음 | 뜻 |
|---|---|---|
code |
예 | 안정된 기계용 식별자. 클라이언트는 이것으로 분기한다 |
category |
예 | Category enum 이름(VALIDATION, CONFLICT …) |
message |
예 | 사용자에게 보여도 되는 한국어 문구(ClientErrorMessages). 분기에 쓰지 않는다 |
retryable |
예 | 같은 요청을 다시 보내도 안전하고 의미가 있는지 |
details |
아니오 | 코드별 구조 정보(검증 실패 필드 목록, bulk 항목 결과). 없으면 키도 없다 |
meta 키
| 키 | 언제 있나 |
|---|---|
requestId |
요청 id 필터(WebMvcRequestIdFilter)를 지난 모든 응답 |
traceId |
위와 같음. 추적이 꺼져 있어도 필터가 만든 W3C trace id가 들어간다 |
correlationId |
위와 같음. 값이 없으면 키가 없다 |
page |
페이지 목록 응답에만. number·size·total·sort(미정렬이면 sort: null) |
컨트롤러에 닿기 전에 거부된 요청(보안 방화벽이 막은 경로, 필터의 sendError, 필터가 던진 예외)도 같은
실패 Envelope다. 컨테이너가 /error로 넘긴 요청을 EnvelopeErrorController가 status에 맞는 코드로 답한다.
본문에 요청 경로나 시각을 싣지 않는다. 기본 JWT 체인에서도 익명 400이 401로 바뀌지 않는다(재리뷰 RR-02-02).
다만 요청 id 필터를 지나기 전에 끊긴 응답은 meta의 id 키가 빠질 수 있다. 클라이언트는 meta의 모르는 키를
무시한다.
status는 코드 표(HttpStatusErrorCodes)에 있는 것만 그대로 나간다: 401·403·404·405·406·412·413·414·415·429·503.
표에 없는 status는 그 class의 코드로 접힌다 — 4xx(408·409·410·422 등)는 BAD_PARAMETER 400, 5xx(501·502·504
등)는 INTERNAL_ERROR 500(재리뷰 RR-01-13, EnvelopeErrorControllerTest). error.code와 status가 registry
(docs/registries/error-codes.yaml)와 어긋나지 않게 하려는 것이다. 클라이언트는 status가 아니라 error.code로
가르기 때문이다. 필터가 다른 status를 내야 하면 sendError 대신 그 status의 코드로 EnvelopeResponseWriter를
쓰거나, 표에 행을 더한다.
4xx·5xx status로 나가는 본문은 success:true로 감싸지 않는다. 실패 Envelope가 아닌 본문을 오류 status로
돌려주는 핸들러는 그 본문이 그대로 나간다.
왜 이렇게 나가는가
Envelope·BulkEnvelope·ApiError·ResponseMeta는 shared-contract에 있고, 이 leaf는 Java
표준 라이브러리 외에는 의존하지 않는다. 그래서 @JsonInclude를 타입에 붙이지 않고, web 어댑터의
EnvelopeWireFormatConfig가 Jackson mix-in으로 같은 규칙을 Boot의 JsonMapper에 등록한다. 이
어댑터의 모든 HTTP writer(MVC 변환기, 보안 entry point, rate-limit interceptor)가 그 JsonMapper를
쓴다. GraphQL·STOMP·gRPC는 이 타입들을 직렬화하지 않으므로 이 규칙의 영향을 받지 않는다.
2. 멱등성 응답
Idempotency-Key를 받는 쓰기 엔드포인트(KEYED)는 IdempotencyExecutor를 거친다. 같은 키로 다시
보낸 요청은 서버가 아래 넷 중 하나로 판정한다. 키는 인증 주체와 operation 범위 안에서만 같은 키다.
| 경우 | status | error.code |
retryable |
Retry-After |
클라이언트 행동 |
|---|---|---|---|---|---|
| 재생(replay): 같은 키·같은 본문, 첫 요청 완료 | 첫 요청과 같은 성공 status | — (성공 Envelope) | — | 없음 | 첫 요청의 결과로 받아들인다. meta의 id는 이번 요청의 것이다 |
| 처리 중(in-flight): 같은 키, 첫 요청이 아직 실행 중(Redis 저장소. PostgreSQL 저장소는 409 대신 첫 요청이 끝날 때까지 기다린다 — 아래 "첫 시도가 lease보다 오래 걸릴 때") | 409 | IDEMPOTENT_IN_FLIGHT |
true |
2 |
결과 불명. 같은 Idempotency-Key로 Retry-After 뒤 재전송한다. 새 키 금지 |
| 본문 불일치(mismatch): 같은 키·다른 본문 | 422 | IDEMPOTENT_REQUEST_MISMATCH |
false |
없음 | 클라이언트 버그. 다시 보내지 않는다. 새 작업이면 새 키를 만든다 |
| 키 누락·형식 오류 | 400 | IDEMPOTENCY_KEY_INVALID (details.reason = MISSING/MALFORMED) |
false |
없음 | 문법에 맞는 키를 붙여 다시 보낸다 |
- 처리 중을
retryable=true로 두는 이유. 같은 키 재전송은 서버가 재생·처리 중·불일치로 안전하게 판정하므로, 다시 보내는 것이 맞는 행동이다. 새 키로 보내면 서버는 다른 요청으로 보고 막지 못해, 첫 요청이 끝나면 같은 작업이 두 번 적용된다. Retry-After: 2의 근거. 기본 processing lease(app.capabilities.idempotency.processing-lease, 30s)보다 짧아, 첫 시도가 아직 끝날 수 있는 동안 다시 묻는다. 너무 이르면 409를 한 번 더 받을 뿐이고 결과가 바뀌지는 않는다. 값은IdempotencyExecutor.IN_FLIGHT_RETRY_AFTER하나이고RetryAfterAdvisor가 그 값을 쓴다.processing-lease를 이 값(2초) 이하로 설정하면 기동이 실패한다(IdempotencySettings, 재리뷰 RR-02-05).- executor는 기다리지 않는다. 처리 중이면 바로 409를 돌려준다. 키로 결과를 조회하는 엔드포인트는 없다.
- 키 문법: 보이는 ASCII(
0x21–0x7E) 1~256자. 서버는 trim하거나 고치지 않는다. 짝 프론트의isValidIdempotencyKey와 같은 규칙이다. KEYED 엔드포인트는 모두IdempotencyKeyHeader.parse로 헤더를 읽어 같은 코드로 거부한다(리뷰 02-12). 키 원문은 응답에 돌려 쓰지 않는다. 키를 요구하지 않는 엔드포인트는 키 없이 보호 없이 실행된다.
같은 executor가 내는 나머지 세 실패. 저장소가 응답하지 않은 경우는 언제 멈췄는지로 코드가 갈린다.
| 경우 | status | error.code |
retryable |
Retry-After |
클라이언트 행동 |
|---|---|---|---|---|---|
| 작업 실행 전(claim·시작 단계) 멱등성 저장소 응답 없음. 또는 claim의 processing lease가 작업 시작 전에 끝나 저장소가 시작을 거절함 | 503 | IDEMPOTENCY_UNAVAILABLE |
true |
없음 | 작업은 실행되지 않았다. 같은 키로 나중에 다시 보낸다(다음 요청이 그 claim을 넘겨받아 실행한다) |
| 작업 실행 뒤 결과 기록(complete 단계) 중 저장소 응답 없음 — 결과 불명 | 503 | IDEMPOTENCY_COMPLETION_UNKNOWN |
true |
없음 | "적용되지 않았다"고 알리지 않는다. 같은 키로 나중에 다시 보낸다. 새 키 금지 |
| 이전 시도의 효과를 증명할 수 없음 | 500 | IDEMPOTENCY_RECOVERY_REQUIRED |
false |
없음 | 자동 재시도하지 않는다. 같은 키 재전송은 안전하다 — 서버는 효과가 있었을 수 있는 작업을 다시 돌리지 않고, 첫 시도가 늦게 끝났으면 그 결과를 재생하며, 효과 없이 끝났으면 실행하고, 아니면 다시 500이다. 결과는 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차(docs/runbooks/idempotency-unavailable.md)에 따라 새 키로 다시 보낸다 |
-
결과 불명이 무엇을 뜻하나. 작업은 이미 돌았다. 유스케이스가 executor를 쓰기 트랜잭션 안에서 불렀다면 그 트랜잭션의 DB 변경은 예외와 함께 롤백된다. 작업이 자기 트랜잭션을 따로 커밋했다면 그 변경은 남는다. 트랜잭션 밖 효과(다른 시스템 호출, 메시지)는 일어났을 수 있다. 그래서 실행 전 거부와 같은 503이어도 code가 다르다. 클라이언트는 status가 아니라
error.code로 가른다. -
같은 키로 다시 보내면 서버가 판정하고, 작업을 다시 돌리지 않는다. 결과가 실제로는 기록됐으면 재생(첫 요청의 성공 응답), 첫 시도의 processing lease(
processing-lease, 기본 30s)가 아직 남았으면 409IDEMPOTENT_IN_FLIGHT, lease가 지났으면 500IDEMPOTENCY_RECOVERY_REQUIRED다. 이것은 Redis 저장소의 판정이다. PostgreSQL 저장소는 아래처럼 첫 요청이 끝날 때까지 기다린 뒤 판정한다. 새 키로 보내면 서버는 다른 요청으로 보고 막지 못한다(재리뷰 2026-11-03 README 4절 결정 RR-02-03, 2026-11-04 9.1절 결정 RR-01-11). -
첫 시도가 lease보다 오래 걸릴 때 — 저장소마다 다르다. executor는 lease를 늘리지 않으므로 30s를 넘는 정상 요청도 lease가 지난다(재리뷰 2026-11-04 RR5-01-05).
- Redis: lease가 지난 실행 기록을 다음 요청이 만나면 500으로 답하고 기록은 건드리지 않는다. 첫 시도가
그 뒤에 끝나면 결과가 그대로 기록되고, 첫 요청은 자기 응답을 정상으로 받는다. 그 뒤 같은 키 요청은 그
결과를 재생한다. 첫 시도가 실패를 보고하면 먼저 온 보고 하나가 기록된다(효과 불명이면 계속 500, 효과
없는 재시도 가능 실패면 다음 같은 키 요청이 다시 실행한다). 기록이 이미 사라진 뒤에 끝나면 결과를
기록하지 못해 첫 요청도 500
IDEMPOTENCY_RECOVERY_REQUIRED를 받는다(2026-11-04 소유자 결정). - PostgreSQL: 템플릿처럼 executor를 유스케이스의 쓰기 트랜잭션 하나 안에서 부르면 claim 기록은 그
트랜잭션이 끝날 때 함께 커밋되거나 롤백된다. 그래서 같은 키 요청은 409나 500을 받지 않고 그 기록에서
기다린다. 첫 트랜잭션이 커밋되면 재생을, 롤백되면 새 실행을 받는다. lease가 지나도 같다. 작업이 실패해
예외로 끝난 요청은 executor가 남긴 실패 기록도 함께 롤백되므로, 효과 불명 실패도 다음 같은 키 요청이
다시 실행한다. 또 쓰기 트랜잭션 제한(
app.persistence-jpa.transaction.write-timeout, 기본 30s — 기본 lease와 같다, 업그레이드 안내 B-21)이 두 요청에 모두 걸린다. 첫 요청이 그보다 오래 걸리면 취소되고 claim 기록도 함께 롤백된다(503DB_QUERY_CANCELED). 기다리던 요청도 자기 제한을 넘기면 같은 코드로 끝난다. 어느 경우든 롤백된 DB 변경은 남지 않지만, 트랜잭션 밖 효과(다른 시스템 호출, 메시지)는 다음 같은 키 요청에서 두 번 일어날 수 있다. 이 저장소가 막는 중복은 같은 트랜잭션 안의 DB 효과다 (PostgreSqlIdempotencyIntegrationTest).
- Redis: lease가 지난 실행 기록을 다음 요청이 만나면 500으로 답하고 기록은 건드리지 않는다. 첫 시도가
그 뒤에 끝나면 결과가 그대로 기록되고, 첫 요청은 자기 응답을 정상으로 받는다. 그 뒤 같은 키 요청은 그
결과를 재생한다. 첫 시도가 실패를 보고하면 먼저 온 보고 하나가 기록된다(효과 불명이면 계속 500, 효과
없는 재시도 가능 실패면 다음 같은 키 요청이 다시 실행한다). 기록이 이미 사라진 뒤에 끝나면 결과를
기록하지 못해 첫 요청도 500
-
서버가 기억하는 기간. 위 판정은 기록이 남아 있는 동안만 선다. 기록이 사라지면 같은 키는 새 요청으로 실행된다. 기록의 수명은 시도가 어떻게 끝났는지로 갈린다.
- 완료된 응답: 완료부터
replay-ttl(APP_IDEMPOTENCY_TTL, 기본 24h). - 끝나지 않은 시도: claim부터 processing lease +
replay-ttl. lease가 지난 실행 기록도 이 수명을 그대로 쓴다. 그 사이 첫 시도가 끝나면 그때부터 위(완료)나 아래(실패)의 수명으로 바뀐다. - 실패로 표시된 시도: 작업이 예외를 던졌거나 효과 불명으로 끝나 포기(abandoned)된 시도, 효과 없이
재시도 가능으로 끝난 시도. 표시한 때부터
failure-retention(APP_IDEMPOTENCY_FAILURE_RETENTION, 기본 24h). PostgreSQL 저장소를 쓰기 트랜잭션 하나 안에서 쓰면 실패 기록은 요청의 롤백과 함께 사라져 남지 않는다(위 PostgreSQL 항목).
replay-ttl이processing-lease보다 짧으면 기동이 실패한다(재리뷰 2026-11-04 RR-03-11).failure-retention이replay-ttl보다 짧아도 기동이 실패한다. 더 짧으면 효과 불명으로 포기한 기록이 그만큼 먼저 사라지고, 그 뒤 같은 키 재전송은 작업을 다시 돌린다(재리뷰 2026-11-04 RR3-03-02, 2026-11-04 소유자 결정). - 완료된 응답: 완료부터
3. 헤더
요청 id·correlation id
| 헤더 | 방향 | 규칙 |
|---|---|---|
X-Request-Id |
응답(항상) | 서버가 만든다. 신뢰 설정(app.web.mvc.trust-inbound-request-id)일 때만 요청 값을 받는다 |
X-Correlation-Id |
요청·응답(항상) | 요청 값이 [A-Za-z0-9._-]{1,128}(앞뒤 공백 제거 후)이면 그대로 잇고, 아니면 서버가 새로 만든다. 고치지 않고 바꾼다 |
traceparent |
요청·응답(항상) | 유효한 W3C 값이면 잇고, 아니면 새로 만든다 |
세 값은 응답 meta의 requestId·correlationId·traceId와 같다. 셋 다 짝 프론트의
[A-Za-z0-9._:-]{1,128} 안에 든다.
브라우저가 읽을 수 있는 응답 헤더(CORS)
CORS가 켜져 있으면(app.cors.enabled=true) cross-origin 실제 응답의 Access-Control-Expose-Headers에
아래가 들어간다. 이 목록 밖의 헤더(안전 목록 Cache-Control·Content-Type 등 제외)는 브라우저 코드에서
null로 보인다.
- 플랫폼(
CorsExposedHeaders.PLATFORM):Retry-After,X-Request-Id,X-Correlation-Id,traceparent,Location,ETag,X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset - fileserver를 실은 배포:
Tus-Resumable,Tus-Version,Tus-Extension,Tus-Max-Size,Upload-Offset,Upload-Length,Upload-Defer-Length,Upload-Expires,Upload-Complete,Upload-Limit,Content-Disposition,Accept-Ranges,Content-Range
새 응답 헤더를 쓰는 모듈은 CorsExposedHeaders bean으로 자기 헤더를 기여한다.
4. web 전용 오류 코드
OperationalError(docs/registries/error-codes.yaml) 밖에서 HTTP 어댑터가 내는 코드다.
| 코드 | status | category | retryable |
Retry-After |
언제 |
|---|---|---|---|---|---|
REQUEST_TIMEOUT |
503 | TRANSIENT_DEPENDENCY |
true |
없음 | 비동기 요청(Callable·DeferredResult·스트리밍)이 시간 안에 끝나지 않았다. 그 밖의 503(필터의 sendError(503) 등)은 공용 SERVER_BUSY다. GraphQL도 같은 이름을 쓰지만 그쪽 category는 GraphQL 전용 어휘 TIMEOUT이다(src/adapter/inbound/graphql/README.md) |
IDEMPOTENCY_KEY_INVALID |
400 | VALIDATION |
false |
없음 | 2절 |
RATE_LIMIT_UNAVAILABLE |
503 | TRANSIENT_DEPENDENCY |
true |
있음 | rate-limit 저장소 응답 없음(docs/web/runbook.md) |
RATE_LIMIT_INCOMPATIBLE |
503 | INTERNAL |
false |
없음 | rate-limit 제공자가 계약과 맞지 않음 |
OPERATION_NOT_FOUND |
404 | NOT_FOUND |
false |
없음 | durable operation 조회(DurableOperationController)에서 그 operation이 없거나 다른 호출자의 것이다. 둘을 가르지 않는다 |
- 컨트롤러 파라미터 제약 위반(
@RequestParam @Max(10))은 요청 본문 위반과 같은400 VALIDATION_FAILED이고details는[{field, code, message}]다. 거절된 값은 싣지 않는다. - web-advanced를 실은 서비스의 예외 코드(
PATCH_REJECTED400 등)는src/adapter/inbound/web-advanced/README.md「오류 응답」이 정본이다. - 서버 포화(허가 상한, 꽉 찬 work pool)는 모든 전송이 공용
SERVER_BUSY(503, retryable,Retry-After: 1) 하나로 답한다. 호출자 자신의 빈도 초과만RATE_LIMIT_EXCEEDED429다(docs/registries/error-codes.yaml). - 직접 쓰는 거부 응답(401·403·429·503)도 컨트롤러 응답과 같이
application/json;charset=UTF-8이다.
5. 바꿀 때
- 응답 키를 더하거나 빼면
EnvelopeWireShapeTest와 이 문서 1절을 같이 고친다. - 응답 헤더를 새로 쓰면
CorsExposedHeaders에 넣고 3절을 고친다. - 멱등성 코드의 status·retryable·
Retry-After를 바꾸면OperationalError,RetryAfterAdvisor,docs/registries/error-codes.yaml, 이 문서 2절을 같은 변경에서 고친다. 공유 코드의retryable은 gRPC trailer(error-retryable)와 GraphQL extension(retryable)에도 그대로 나가므로 그 둘의 README와 매핑 테스트(GrpcStatusMapperTest,GraphQlWireErrorMapperTest)도 같이 본다. - 짝 프론트 repo
clean-architecture-frontend-template의 백엔드 계약 문서(「backend API와 server state 계약」 §4.1·§6)는 이 문서를 가리켜야 한다. 그 문서는 다른 repo에 있어서 여기서 경로로 가리키지 않는다.