최근 블로그 포스트들의 분류 체계를 깔끔하게 자동 정리하고 싶어졌다. 기존 포스트들의 라벨을 일괄 변경하기 위해 Blogger API 라벨 수정을 시도했다. 하지만 언제나 그렇듯 API 연동 작업은 예상치 못한 에러와의 싸움이었다. 가볍게 끝날 줄 알았던 작업이 꼬이면서 몇 시간 동안 삽질을 이어가야 했다.

원래 계획은 기존 포스트 데이터를 가져와 라벨을 새로 덮어쓰는 단순한 자동화 스크립트를 실행하는 것이었다. 그러나 실제로 스크립트를 가동하자마자 터져 나오는 에러 메시지들을 보며 당황할 수밖에 없었다. 내가 겪은 시행착오와 해결 과정을 상세히 기록해 둔다.

bypath 404 오류와 커스텀 도메인의 함정

가장 먼저 부딪힌 문제는 posts/bypath API를 호출할 때 발생한 404 에러였다. 공식 문서를 참고하여 경로 기반으로 포스트를 수정하려고 했으나 계속해서 요청을 찾을 수 없다는 오류가 반환되었다. 원인을 분석해 보니 블로그에 연동해 둔 커스텀 도메인이 문제였다.

Blogger API는 커스텀 도메인을 사용하는 환경에서 bypath 호출 시 404 에러를 내뱉는 고질적인 한계가 있었다. 이를 해결하기 위해 포스트의 전체 데이터를 전송하는 PUT 방식도 시도해 보았지만, 이 또한 풀바디 요청 실패로 이어졌다. 결국 API 설계 단계에서부터 다른 우회 경로를 찾아야만 했다.

400 에러의 원인 추적과 debugPatchOne

bypath를 포기하고 본격적으로 backfillLabels() 함수를 구현하여 포스트 8건에 대해 일괄 라벨 수정을 실행했다. 하지만 결과는 처참했다. 8건 중 무려 5건에서 400 Bad Request 에러가 발생하며 작업이 중단되었다.

무엇이 문제인지 명확히 파악하기 위해 최소 단위의 테스트용 함수인 debugPatchOne()을 급히 만들었다. 아주 단순한 2개의 라벨만 담아서 최소한의 스펙으로 PATCH 요청을 보내보았다. 놀랍게도 이 요청은 200 OK를 반환하며 성공적으로 작동했다.

이를 통해 API 자체나 권한의 문제가 아님을 확신할 수 있었다. 원인은 바로 AI가 자동으로 생성해 준 16개의 라벨 배열에 있었다. 라벨 목록에 포함된 특수문자와 지나치게 긴 텍스트 길이가 API 규격을 벗어나 400 에러를 유발한 것으로 추정되었다.

안전한 우회 방식과 patchFailedPosts 구현

결국 문제가 된 포스트들을 구제하기 위해 수동과 자동을 적절히 섞은 해결책을 고안했다. 우선 문제가 되는 라벨들을 7개 이하의 안전하고 정제된 하드코딩 라벨 배열로 재정의했다. 그리고 이 라벨들을 안전하게 주입해 줄 patchFailedPosts() 함수를 새롭게 작성하여 적용했다.

또한 앞서 겪었던 커스텀 도메인 하에서의 bypath 404 문제를 해결하기 위해 포스트 접근 방식을 완전히 바꾸었다. 경로로 직접 접근하는 대신 posts.list API를 통해 전체 포스트 목록을 먼저 불러왔다. 그 후 가져온 데이터에서 제목 매칭을 수행하여 수정 대상을 타겟팅하는 방식으로 우회에 성공했다.

Blogger API 라벨 수정을 마치며 얻은 교훈

이번 작업을 통해 API 자동화를 진행할 때는 예외 처리가 얼마나 중요한지 다시금 뼈저리게 느꼈다. 특히 외부 AI가 생성한 메타데이터를 정제 없이 API 요청에 바로 밀어 넣는 것은 매우 위험하다는 점을 배웠다. 반드시 글자 수 제한이나 특수문자 필터링 같은 전처리 단계를 거쳐야 안전하다.

또한 플랫폼 특유의 도메인 제약 사항도 미리 체크해 두어야 시간 낭비를 줄일 수 있다. 비록 삽질은 길었지만 posts patch 과정과 도메인 우회 로직을 확실하게 마스터할 수 있었던 값진 경험이었다. 혹시 나와 같은 에러로 고통받고 있다면 이 해결 방식이 힌트가 되기를 바란다.