결론부터
- 1파일 참조에는 유효 기간 — 만료 오류는 정상 흐름이다.
- 2파일이 있던 메시지·프로필·스티커 묶음을 다시 받아 새 참조로.
- 3파일 번호별로 지금 참조와 원래 자리를 함께 저장해 둔다.
파일 참조란
텔레그램 API 에서 사진·문서 같은 파일 정보에는 파일 번호 말고도 파일 참조(file_reference)라는 바이트 값이 함께 붙어 옵니다. 파일을 받으려면 이 참조를 같이 내야 합니다. 참조에는 유효 기간이 있어서, 오래 저장해 둔 참조로 받으려 하면 거절됩니다. 한 번 본 파일 정보를 영원히 쓰지 못하게 하려는 장치입니다.
만료되면 오는 오류
| 오류 | 뜻 |
|---|---|
| FILE_REFERENCE_EXPIRED | 참조의 기간이 지났다 |
| FILE_REFERENCE_INVALID 등 | 참조가 맞지 않는다 — 이 역시 새로 받는다 |
이 오류는 버그가 아니라 정상적인 흐름입니다. 파일이 원래 들어 있던 곳을 다시 받아 새 참조를 얻은 뒤, 같은 요청을 다시 보냅니다.
어디서 다시 받나
| 파일이 있던 곳 | 다시 받는 방법 |
|---|---|
| 대화 메시지 | 그 메시지를 다시 받기 — 일반 대화는 messages.getMessages, 채널은 channels.getMessages |
| 사용자 프로필 사진 | 그 사용자의 사진 목록 다시 받기 |
| 스티커 | 그 스티커 묶음 다시 받기 |
| 배경화면·테마 | 그 배경·테마 정보 다시 받기 |
| 스토리 | 그 스토리 다시 받기 |
미리 대비하는 저장 방식
공식 문서는 파일을 오래 다루는 앱이라면 두 가지를 함께 저장해 두라고 권합니다.
- 파일 번호 → 지금 참조: 새 참조를 받을 때마다 갈아 끼웁니다.
- 파일 번호 → 그 파일이 있던 곳(어느 대화의 몇 번 메시지 등): 오류가 나면 여기를 보고 원래 자리를 다시 받습니다.
이렇게 해 두면 참조가 만료돼도 사용자 모르게 자동으로 새로 받아 이어 갈 수 있습니다.
자주 묻는 질문
FILE_REFERENCE_EXPIRED 는 왜 나나요?
파일 정보에 붙은 파일 참조의 유효 기간이 지나서입니다. 버그가 아니라 정상적인 흐름입니다.
어떻게 해결하나요?
파일이 들어 있던 메시지·프로필 사진·스티커 묶음 등을 다시 받아 새 참조를 얻고 같은 요청을 다시 보냅니다.
채널 메시지의 파일은 어떻게 다시 받나요?
channels.getMessages 로 그 메시지를 다시 받습니다. 일반 대화는 messages.getMessages 입니다.
봇 API 의 file_id 도 만료되나요?
봇 API 의 file_id 는 다른 체계라 같은 봇 안에서 다시 쓸 수 있습니다. 이 처리는 MTProto 를 직접 다룰 때 필요합니다.
참고한 공식 문서
요약
한눈에 정리
- 1참조
유효 기간이 있다.
- 2만료면
원래 자리 다시 받기.
- 3저장
참조 · 원래 자리.
최종 수정 2026-10-06
