클라이언트가 반영할 백엔드 계약 변경

백성검 님께. 8월 26일부터 백엔드 계약이 여러 번 늘었는데 한 번에 정리해 전달한 적이 없었습니다. 오늘 문서로 묶었습니다.

받는 법

git pull

fastapi/docs/client-contract-changes.md 입니다. Claude 에게 이렇게 주시면 바로 처리됩니다.

fastapi/docs/client-contract-changes.md 를 읽고 "조치 필요"로 표시된 것만 처리해줘.

무엇이 들어 있나

아홉 건인데 정말 손대야 하는 것은 둘입니다. 나머지는 이미 잘 돌고 있어서 ✅ 조치 불필요 로 표시하고 왜 그런지도 적었습니다 — 멀쩡한 코드를 건드리지 않으시도록.

#	변경	www	Flutter
1	429 TOO_MANY_REQUESTS (인증 3경로, 1분 10회)	🔴 조치 필요	🔴 조치 필요
2	409 CANNOT_DELETE_SELF	🟡 선택 (동작은 정상)	—
3	q 는 패턴이 아니라 글자	🟡 선택	—
4	Flutter 가 에러 code 를 버린다	✅	🔴 1번의 선행 조건
5~9	토큰 폐기 · 빈 계정 · /docs 등	✅ 알고만 계시면 됩니다	✅

가장 중요한 하나

🔴 429 에서 즉시 재시도하면 제한이 영영 안 풀립니다. 창이 60초라서 재시도가 그 안에 계속 들어오면 카운터가 계속 차 있습니다. Retry-After 헤더는 아직 없어서 (붙일 예정입니다) 클라이언트가 자체적으로 간격을 두어야 합니다.

확인하고 쓴 것

문서에 적은 파일 경로와 “지금 이렇게 되어 있다”는 서술을 전부 실제 코드로 확인했습니다(20건). 없는 파일이나 이미 처리된 것을 시키지 않습니다.

특히 www/ 는 구조가 좋아서 대부분 그대로 잘 돕니다. ApiCallError 가 status 와 code 를 끝까지 들고 있어서, 예를 들어 강제 탈퇴 버튼은 409 를 받아도 서버 문구를 보여주고 정상으로 돌아옵니다. 고장 난 곳이 아니라 “다시 못 누르게 하는 쪽”이 비어 있는 것이라 그렇게 적었습니다.

Flutter 는 AuthException 이 message 만 갖고 code 를 버려서 분기 자체가 불가능합니다. 그것부터 열어야 429 를 다룰 수 있습니다.

요청

계약이 클라이언트 쪽에서 쓰기 불편하면 백엔드를 고치는 편이 맞습니다. 애매한 곳이 있으면 알려 주세요. 전체 규격은 fastapi/docs/api-contract.md 입니다.