재시도 전에 요청과 로컬 상태 확인
이 가이드는 공식 Reddit API가 아닌 독립적인 과거 아카이브의 조회 통합을 다룹니다. 투명한 요청 전달, Reddit OAuth 인증이나 제한 우회 기능을 제공하지 않습니다. 게시, 투표와 메시지 전송도 지원하지 않습니다. 읽기 전용이라는 점은 쓰기 기능이 없다는 뜻이며 응답이 영구히 고정되거나 반복 실행에 비용이 들지 않는다는 뜻은 아닙니다. 오류 처리에서는 요청 자체, 서버 성공 여부와 클라이언트 저장 여부를 각각 구분해야 합니다.
먼저 호스트, 경로, 매개변수와 사용하는 키의 도메인을 확인하세요. 댓글 헤더 점검이라면 https://api.redditapiproxy.com/v1/comments?subreddit=devops&limit=3 처럼 범위를 좁힐 수 있습니다. Authorization: Bearer YOUR_API_KEY 또는 X-API-Key: YOUR_API_KEY를 사용하고 Bearer 값에 Reddit OAuth 토큰을 넣지 마세요. 로그에는 실제 인증 값을 제외한 경로, 필터, 실행 시각과 상태 코드를 남기세요. 서로 다른 시도의 기록이 섞이지 않도록 로컬 처리 식별자를 두는 것은 클라이언트에서 선택할 수 있는 방법입니다.
응답을 받은 뒤 파일 기록이나 후속 처리가 실패했다면 먼저 로컬에 남은 결과를 확인하세요. 이미 받은 데이터를 다시 처리할 수 있는지 확인하면 불필요한 조회를 줄일 수 있습니다. 다만 읽기 전용이라는 이유로 같은 요청의 내용이 언제나 같다고 가정하지 마세요. 로컬 처리에서 중복을 제거한다면 어떤 식별자와 규칙을 썼는지 기록하세요. 이 절차가 아카이브 전체의 중복 없는 수집이나 빠진 기록의 복원을 증명하는 것은 아닙니다.
HTTP 상태별로 원인 좁히기
400 응답에는 같은 요청을 그대로 반복하기보다 매개변수를 점검하세요. 날짜는 UTC 기준 YYYY-MM-DD이며 to는 해당 날짜 전체를 포함합니다. kind는 post 또는 comment를 사용합니다. min_score는 최소 점수 필터이지 정렬 지시가 아닙니다. 식별자 조회는 /v1/item?id=... 를 사용하며 /v1/posts나 /v1/comments에 id 필터를 넣지 마세요. 반환된 parent_id와 link_id도 목록 조회 필터로 사용할 수 없습니다.
401이면 키가 빠졌거나 유효하지 않은지 확인하세요. 다른 도메인의 키를 사용했거나 재생성으로 무효화된 이전 키가 설정에 남아 있을 수 있습니다. 로그인 세션 쿠키가 있다는 사실만으로 조회 헤더가 올바른 것은 아닙니다. 키를 재생성하려면 로그인 상태에서 비밀번호 확인이 필요하며 이전 키는 즉시 무효화됩니다. 따라서 무작정 키를 바꾸기보다 현재 설정과 실행 환경을 먼저 확인하고 변경이 필요한 클라이언트의 범위를 파악하세요.
402이면 해당 도메인의 잔액을 확인하고 충전이 필요하다면 로그인 후 청구서를 생성하세요. 키만 바꾸어도 잔액 문제가 해결되는 것은 아닙니다. 429이면 동시 실행 수와 호출 빈도를 줄이고 대기 간격을 둔 제한적인 재시도를 고려하세요. 반복 횟수와 중단 조건은 클라이언트에서 정해야 합니다. 대기하면 반드시 해제된다고 약속할 수 없으며 여러 계정을 만들어 제한을 피하는 방식으로 대응해서도 안 됩니다.
비용과 결과 범위 기록
성공한 조회는 빈 결과라도 크레딧 하나를 사용합니다. 유효하지 않은 요청은 차감되지 않고 상위 시스템 실패의 예약분은 반환됩니다. 그러나 클라이언트의 시간 초과나 연결 종료만으로 서버 실패를 확정할 수는 없습니다. 서버에서는 조회가 성공하고 응답만 유실되었을 수 있습니다. 다시 보낸 요청이 성공하면 추가 크레딧이 사용될 수 있으므로 모든 통신 오류에 자동 환불이 적용된다고 계산하지 말고 재시도 예산과 실행 기록을 함께 관리하세요.
결과는 평평한 레코드이며 관계 분석이 필요할 때만 parent_id와 link_id로 선택적으로 그룹화할 수 있습니다. 읽기와 단순 집계에는 트리가 필요하지 않고 누락된 부모나 댓글은 이 작업으로 복구되지 않습니다. 최대 100개 레코드와 쿼리당 100페이지 한도, 아카이브 문서 순서를 고려하세요. eq는 정확한 총계, gte는 하한, unknown 또는 null은 신뢰할 총계를 알 수 없는 상태입니다. 총계나 페이지 반복만으로 전체 수집 완료를 주장하면 안 됩니다.
공개 비과금 /v1/status는 정적인 서비스 범위와 HTTP 응답 여부를 알려 줄 뿐 검색 저장소를 검사하지 않습니다. 특정 기록의 존재, 키의 유효성이나 잔액도 확인하지 않으므로 실제 조회 성공의 대체 지표로 사용하지 마세요. 문서에서 필터를 확인하고 요금 페이지에서 요청 단위 비용을 검토한 뒤 필요한 조회만 실행하세요. 결과를 공유할 때는 실행 조건과 실제 받은 범위를 설명하고 실시간성, 영구 보존이나 가용성에 대한 보장을 덧붙이지 마세요.
