자동 게시가 조용히 멈췄을 때 먼저 볼 것
지난 어느 아침 로그를 열었더니 릴스 게시 작업이 전부 실패로 찍혀 있었다. 크론은 제 시간에 떴고 스크립트도 끝까지 돌았는데, 인스타에는 아무것도 올라가지 않았다. 처음엔 서버가 죽은 줄 알았다.
이 문제가 까다로운 이유가 여기 있다. 크론 상태는 성공으로 보여도 실제 발행 호출은 실패했을 수 있다. 에러를 잡아서 로그에만 남기고 정상 종료하는 스크립트라면 대시보드는 초록색인데 게시물은 없다. ClipSquare, Folio Studio, 모션팩토리 홍보 영상을 크론이 하루 한 번씩 올리는 구조라서, 토큰 하나가 죽으면 브랜드 세 개가 한꺼번에 조용해진다.
제일 먼저 할 일은 로그에 찍힌 에러 메시지 원문을 그대로 복사해 두는 것이다. “토큰 에러 같다”고 요약해 두면 나중에 판단이 흔들린다. 나도 처음엔 “OAuth 에러”라고만 메모했다가 원문을 다시 찾느라 헤맸다.
흔한 실수는 에러에 토큰이라는 단어만 보여도 바로 재발급부터 하는 것이다. 원인이 권한이면 재발급해도 똑같이 실패한다. 나도 그렇게 한 번 돌아간 적이 있다.
토큰 만료인지 권한 문제인지 가르는 진단 순서
순서는 세 단계다. 에러 코드를 보고, 토큰 상태를 확인하고, 발행 API를 직접 호출해서 재현한다. 이 순서를 지키면 재발급이 필요한지 재승인이 필요한지 대부분 갈린다.
에러 코드로 1차 구분한다. 토큰 자체 문제면 보통 190 계열이 온다. 권한이 빠졌다면 200번대 권한 에러나 메시지에 permission 계열 문구가 붙는다. 정확한 문구는 상황마다 달라서 아래 표는 내가 본 형태 기준이다. 판정은 표가 아니라 로그 원문으로 한다.
| 구분 | 에러 코드 단서 | debug_token의 is_valid | scopes 확인 | 조치 |
|---|---|---|---|---|
| 토큰 만료 | 190 계열, 세션 만료 문구 | false | 확인 불가 | 장기 토큰 재발급 |
| 토큰 무효 | 190 계열, 유효하지 않은 토큰 문구 | false | 확인 불가 | 재발급 |
| 권한 빠짐 | 10 또는 200번대 권한 문구 | true | 게시 권한 누락 | 권한 재승인 |
토큰이 살아 있는지는 debug_token으로 본다. is_valid가 true인데 권한 에러가 나면 재발급은 소용이 없다. scopes에 게시 권한이 있는지 같이 본다.
curl -s "https://graph.facebook.com/debug_token?input_token=<IG_TOKEN>&access_token=<APP_ID>|<APP_SECRET>"
마지막은 발행 경로를 직접 호출해서 재현하는 것이다. debug_token이 정상인데 게시만 안 되면 크론 스크립트보다 호출 경로를 먼저 의심한다. 나는 이 단계를 건너뛰고 갱신부터 했다가, 권한이 해제된 이력이 원인이었던 적이 있다. 토큰을 새로 받아도 그 토큰에 게시 권한이 없으면 같은 자리에서 또 멈춘다.
권한 문제는 토큰 교체로 풀리지 않는다. 앱 설정이나 계정 연결이 바뀌면 사람이 로그인해서 다시 승인해야 한다.
단기 토큰과 장기 토큰, 갱신은 언제 하나
| 항목 | 단기 토큰 | 장기 토큰 |
|---|---|---|
| 수명 | 짧다 (정확한 기간은 공식 문서에서 확인) | 단기보다 길다 (정확한 기간은 공식 문서에서 확인) |
| 발급 방식 | 로그인 직후 받는다 | 단기 토큰을 교환해서 받는다 |
| 갱신 | 교환이 필수다 | 만료 전 갱신할 수 있고, 시간 조건이 붙는다 |
단기 토큰은 그대로 쓰면 금방 만료되니 장기 토큰으로 교환해서 쓴다. 교환 요청은 아래 모양이다. 실제 값은 직접 채운다. 로그인 방식에 따라 엔드포인트가 달라지니 공식 문서에서 맞는 흐름을 먼저 확인한다.
curl -s "https://graph.facebook.com/v{API_VERSION}/oauth/access_token?grant_type=fb_exchange_token&client_id=<APP_ID>&client_secret=<APP_SECRET>&fb_exchange_token=<SHORT_LIVED_TOKEN>"
놓치기 쉬운 건 만료일을 머릿속에만 두는 것이다. 나는 만료일을 달력에 적고, 그 날짜 기준으로 갱신 여유를 잡는다. 만료 직전에 갱신을 시도했다가 실패한 적도 있었다. 그때는 새 단기 토큰을 받아서 다시 교환하는 쪽으로 넘어갔다.

토큰을 갱신한 뒤 자동 게시를 다시 확인하는 순서
토큰을 바꾸고 끝내면 다음 크론에서 또 멈출 수 있다. 실제로 그랬다. 파일은 새 값으로 바뀌었는데 실행 중인 워커가 구 토큰을 메모리에 들고 있었다.
- 새 토큰을 서버 환경변수와 크론이 읽는 설정 파일에 반영한다. 성공 기준은 두 곳의 값이 같은 것이다.
- 워커와 관련 프로세스를 재시작한다. 성공 기준은 재시작 후 로그에 찍히는 토큰 식별값이 바뀌어 있는 것이다. 로그에는 토큰을 마스킹해서 찍어야 한다.
- 테스트 컨테이너를 만든다. 성공 기준은 상태 조회에서 FINISHED가 나오는 것이다.
- 컨테이너로 발행을 호출한다. 성공 기준은 응답에 게시물 ID가 오는 것이다.
- 크론 스크립트를 한 번 수동으로 실행한다. 성공 기준은 로그에 같은 게시물 ID가 남는 것이다.
- 실제 계정 화면에서 게시물이 보이는지 확인한다. 성공 기준은 로그의 ID와 화면의 게시물이 맞는 것이다.
curl -s -X POST "https://graph.facebook.com/v{API_VERSION}/<IG_USER_ID>/media" -d "media_type=REELS" -d "video_url=<PUBLIC_TEST_VIDEO_URL>" -d "access_token=<NEW_TOKEN>"
curl -s "https://graph.facebook.com/v{API_VERSION}/<CONTAINER_ID>?fields=status_code&access_token=<NEW_TOKEN>"
테스트 영상 URL은 외부에서 접근 가능해야 한다. 여기서 막히면 토큰 문제가 아니라 영상 주소 문제일 수 있다.

만료 날짜를 미리 알고 알림을 거는 방법
만료된 뒤에 알면 이미 늦다. 나는 알림 채널을 하나만 달아 뒀다가 그 알림이 다른 메시지에 묻혀서 놓친 적이 있다. 무인으로 돌리는 환경이라면 채널 한 곳이 조용해지는 순간 아무도 모른다. 지금은 두 채널로 보낸다.
만료 시각은 매일 조회한다. 임계값은 D-14, D-3, 만료 당일에 걸리도록 잡았다. 크론에 매일 한 번 걸어 두면 된다.
#!/bin/bash
# 인스타 토큰 만료 점검 (크론 매일 1회, 예: 0 9 * * *)
RESP=$(curl -s "https://graph.facebook.com/debug_token?input_token=$IG_TOKEN&access_token=$FB_APP_ID|$FB_APP_SECRET")
read VALID EXP <<< $(echo "$RESP" | python3 -c 'import sys,json; d=json.load(sys.stdin).get("data",{}); print(int(bool(d.get("is_valid"))), d.get("expires_at",0))')
if [ "$VALID" != "1" ]; then
MSG="인스타 토큰 무효, 재발급 필요"
elif [ "$EXP" -eq 0 ]; then
exit 0
else
LEFT=$(( (EXP - $(date +%s)) / 86400 ))
if [ "$LEFT" -eq 14 ] || [ "$LEFT" -eq 3 ] || [ "$LEFT" -le 0 ]; then
MSG="인스타 토큰 만료까지 D-$LEFT"
else
exit 0
fi
fi
curl -s -X POST "$ALERT_WEBHOOK" -H "Content-Type: application/json" -d "{\"text\":\"$MSG\"}"
curl -s -X POST "$MAIL_WEBHOOK" -d "text=$MSG"
만료가 없는 토큰은 expires_at이 0으로 온다. 그래서 스크립트에서 따로 빠지게 해 뒀다. ALERT_WEBHOOK과 MAIL_WEBHOOK은 각자 쓰는 메신저와 메일 수단에 맞게 바꾸면 된다.
알림은 한 번도 울려 본 적 없는 상태로 두면 믿을 수 없다. 정해진 날 IG_TOKEN을 일부러 비운 상태로 스크립트를 돌려서, 두 채널에 메시지가 실제로 도착하는지 본다. 이 테스트를 빼먹으면 알림 체계가 있다는 착각만 남는다.

토큰을 서버와 깃허브에 안전하게 두는 법
토큰은 코드에 직접 쓰지 않는다. 서버에서는 환경변수나 접근 권한을 제한한 설정 파일에 둔다. 설정 파일은 .gitignore에 넣어서 깃허브에 올라가지 않게 한다.
로그도 조심해야 한다. 요청 URL을 통째로 찍으면 access_token이 그대로 남는다. 출력 전에 토큰 앞뒤 일부만 남기고 가리는 함수를 한 번 거치게 해 두었다.
노출이 의심될 때 순서는 정해져 있다. 먼저 해당 토큰을 폐기하고 새로 발급한다. 다음으로 서버 설정을 새 값으로 바꾼다. 깃 히스토리에 남은 흔적은 맨 마지막에 지운다. 히스토리부터 고치면 그 사이에 이미 가져간 사람이 있을 수 있어서, 폐기가 맨 앞이어야 한다.
자동화로 못 푸는 경우와 요약 체크리스트
스크립트가 할 수 있는 건 만료를 알리는 데까지다. 계정 정책이 바뀌었거나, 권한을 다시 승인해야 하거나, 연결된 계정 자체가 바뀌었을 때는 사람이 직접 로그인해서 승인 화면을 다시 거쳐야 한다. 이건 아직 자동화하지 못했고, 앞으로도 자동으로 두지 않을 생각이다.
운영하면서 반복한 실수는 세 가지쯤이다. 에러를 기억에 의존해서 요약하는 것, 원인을 보기 전에 재발급부터 하는 것, 재시작을 빼먹는 것이다.
- 에러 메시지 원문을 로그에서 그대로 복사해 둔다
- debug_token으로 is_valid와 scopes를 확인한다
- 권한 문제면 재발급 대신 재승인으로 간다
- 새 토큰을 서버 설정과 크론 파일 두 곳에 같이 반영한다
- 워커와 관련 프로세스를 재시작한다
- 테스트 컨테이너를 만들고 FINISHED 상태를 확인한다
- 크론을 한 번 수동 실행하고 게시물 ID를 대조한다
- 만료일을 달력에 적고 만료 점검 스크립트를 매일 돌린다
- 알림 채널을 두 곳으로 나누고 정해진 날 테스트 알림을 보낸다
- 토큰 값은 코드, 로그, 깃 어디에도 남기지 않는다
근거로 삼은 문서
1인 빌더 아일리고가 씁니다. 잘된 것도 망한 것도 적습니다. 영상은 제가 만든 ClipSquare 에서 나옵니다.
자주 묻는 질문
인스타 액세스 토큰이 만료되면 릴스 자동 게시는 어떻게 되나요?
에러가 나도 스크립트가 로그만 남기고 정상 종료하면 크론 상태는 성공으로 보이는데 실제 게시는 일어나지 않습니다. 저도 로그를 열어 보고서야 릴스 작업이 전부 실패로 찍힌 걸 알았습니다. 그래서 대시보드 초록불만 믿지 말고 로그의 에러 원문을 먼저 확인하는 게 좋습니다.
크론은 성공인데 인스타에 게시물이 안 올라갈 때 토큰 문제인지 어떻게 구분하나요?
먼저 에러 코드 원문을 그대로 복사해 두고, 190 계열이면 토큰 만료나 무효 쪽, 10이나 200번대 권한 문구면 권한 쪽으로 1차 분류합니다. 그다음 debug_token으로 is_valid와 scopes를 확인하고, 마지막으로 발행 API를 직접 호출해서 재현해 봅니다. 이 순서로 보면 재발급이 필요한지 재승인이 필요한지 대부분 갈립니다.
debug_token에서 is_valid가 true인데 게시가 실패하면 무엇을 봐야 하나요?
토큰은 살아 있으니 재발급해도 같은 자리에서 또 실패합니다. scopes에 게시 권한이 빠져 있는지 먼저 보고, 빠졌다면 사람이 다시 로그인해서 권한을 승인해야 합니다. 권한이 정상인데도 게시가 안 되면 크론 스크립트보다 발행 호출 경로를 먼저 의심해 보세요.
토큰을 새로 발급해서 파일에 넣었는데도 다음 크론에서 또 멈추는 이유는 뭔가요?
파일이나 환경변수는 바뀌었어도 이미 떠 있는 워커 프로세스가 구 토큰을 메모리에 들고 있을 수 있습니다. 저도 이걸 놓쳐서 같은 문제가 다음 실행에서 다시 났습니다. 값을 바꾼 뒤 워커와 관련 프로세스를 재시작하고, 로그에 찍힌 토큰 식별값(마스킹된 값)이 바뀌었는지 확인하세요.
장기 토큰은 언제 갱신해야 하나요?
만료일을 머릿속에만 두지 말고 달력에 적어서 그 날짜 전에 여유를 두고 갱신하는 게 안전합니다. 저는 만료 직전에 갱신을 시도했다가 실패한 적이 있어서, 그 뒤로는 여유를 넉넉히 잡습니다. 정확한 수명과 갱신 조건은 로그인 방식마다 다르니 공식 문서에서 확인하세요.
