Reddit App API · 03 / APP

검색 화면에는 결과와 오류 이외의 상태도 필요합니다

하이킹 앱 설계에서 로딩, 정상적인 빈 결과, 요청 실패를 구분합니다. 사용자에게 유용한 안내를, 운영자에게 적절한 진단 조치를 제공합니다.

로컬 단위 예제가상의 로컬 예제입니다. 요청을 보내지 않습니다.

화면

준비

가상의 로컬 예제입니다. 요청을 보내지 않습니다.

offline maps

{
  "request_sent": false
}

화면

로딩 중

가상의 로컬 예제입니다. 요청을 보내지 않습니다.

{
  "request_in_flight": true
}

화면

레코드

가상의 로컬 예제입니다. 요청을 보내지 않습니다.

offline maps

{
  "data": [
    {
      "id": "fictional-001",
      "kind": "post",
      "title": "offline maps",
      "text": "가상의 로컬 예제입니다. 요청을 보내지 않습니다.",
      "subreddit": "hiking",
      "score": 7,
      "created_utc": 1704067200
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 3,
    "total": 1,
    "relation": "eq",
    "has_more": false,
    "window_exhausted": false,
    "truncated": false
  },
  "credits": {
    "cost": 1,
    "balance": 99
  }
}

화면

결과 없음

가상의 로컬 예제입니다. 요청을 보내지 않습니다.

{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 3,
    "total": 0,
    "relation": "eq",
    "has_more": false,
    "window_exhausted": false,
    "truncated": false
  },
  "credits": {
    "cost": 1,
    "balance": 99
  }
}

화면

401 · invalid_api_key

가상의 로컬 예제입니다. 요청을 보내지 않습니다.

{
  "error": "invalid_api_key"
}

화면

402 · insufficient_credits

가상의 로컬 예제입니다. 요청을 보내지 않습니다.

{
  "error": "insufficient_credits"
}

화면

429 · rate_limited

가상의 로컬 예제입니다. 요청을 보내지 않습니다.

{
  "error": "rate_limited"
}

화면

502 · upstream_unavailable

가상의 로컬 예제입니다. 요청을 보내지 않습니다.

{
  "error": "upstream_unavailable"
}

가상의 로컬 예제입니다. 요청을 보내지 않습니다.

서비스 상태판이 아닌 화면 흐름 예시

개발자가 직접 만드는 하이킹 앱의 상태 제안입니다. 캡처한 API 응답이나 작동하는 화면의 시연이 아니며, 오프라인 지도 레코드가 있다는 증거도 아닙니다. 하이킹 이용자는 앱을 쓰고, API 계정 운영자는 서비스 인증 정보와 크레딧을 관리합니다. 각자가 행동으로 옮길 수 있는 정보를 제공하세요.

첫 검색 전에 과거 토론을 읽는 기능임을 설명하세요. offline maps 같은 검색어 제안은 시작에 도움이 되지만, 검색하기도 전에 지어낸 추천을 검색된 결과처럼 표시해서는 안 됩니다. 명시적인 「검색」 동작을 두어 입력하거나 폼을 살펴보는 것만으로 유료 요청이 발생하지 않게 하세요.

로딩 중에도 질문을 보이게 하세요

응답을 기다리는 동안 제출한 쿼리와 선택한 필터를 유지합니다. 결과 영역을 로딩 중으로 표시하고, 해당 동작의 중복 제출을 막으며, 애니메이션과 함께 접근 가능한 텍스트 안내를 제공하세요. 지연된다는 사실만으로 서비스 장애나 원인을 알 수는 없습니다.

이전 응답이 도착하기 전에 사용자가 쿼리를 바꾸면 각 응답을 제출 당시의 입력과 연결하세요. 예전 질문의 결과를 새 질문 아래에 조용히 넣지 마세요. 이는 직접 테스트해야 할 앱 구현의 선택이며, 아카이브 API가 제공하는 순서 제어나 취소 동작이 아닙니다.

성공한 응답에 레코드가 없을 수도 있습니다

레코드가 있으면 제공된 필드만 표시하고 과거 자료임을 알립니다. 댓글에는 제목이 없을 수 있고 날짜가 빠졌다면 알 수 없는 값으로 남겨야 합니다. pagination.relation이 gte 또는 unknown일 때 정확한 일치 총수를 선언하지 말고, 현재 보이는 페이지를 설명하세요.

정상적인 빈 응답은 별도의 결과입니다. 「이 요청에서는 레코드가 반환되지 않았습니다」라고 안내할 수 있습니다. 기존 입력을 유지한 채 문구나 필터를 의도적으로 바꾸도록 하세요. 그런 토론이 어디에도 없다고 주장하지 마세요. 정상적인 빈 조회도 1크레딧을 사용합니다.

400, 401, 402는 담당자가 다릅니다

HTTP 400은 잘못된 요청 입력을 나타냅니다. 지원하지 않는 매개변수, 범위를 벗어난 페이지, YYYY-MM-DD 형식이 아닌 날짜 등 실제 문제를 확인하세요. 사용자가 고칠 수 있는 필드는 설명하고, 백엔드의 명세 위반은 운영자 진단으로 남깁니다.

HTTP 401은 서비스 API 키가 없거나 유효하지 않다는 뜻입니다. 사용자의 앱 세션이 만료되었다는 증거가 아니며, 이 API 키에는 문서화된 시간 기반 만료 기능이 없습니다. 운영자가 도메인 전용으로 저장한 키와 최근 재생성 여부를 확인합니다. 사용자에게 키를 입력하거나 서비스 계정에 로그인하라고 요구하지 마세요.

HTTP 402는 서비스 계정의 크레딧 부족을 뜻합니다. 사용자에게는 「토론 검색을 잠시 중단했습니다」라고 안내할 수 있습니다. 운영자는 「키와 크레딧」에 로그인해 잔액을 확인합니다. 원인을 처리한 뒤 새 요청을 보내는 것은 별도의 동작이며, 예전 요청을 반복하는 것 자체는 해결책이 아닙니다.

429, 상위 시스템 실패, 응답 전달 여부 불명

HTTP 429는 요청 속도 제한에 도달했다는 뜻입니다. Retry-After를 지키고 중복 제출을 줄이며, 적절한 시점에 다시 시도하게 하세요. 공용 백엔드나 계정에 적용되는 제한일 수 있으므로 특정 사용자의 탓으로 돌리지 마세요. 무제한 자동 재시도 루프를 만들지 않아야 합니다.

게이트웨이는 상위 시스템 실패를 HTTP 502로 알립니다. 쿼리를 유지하고, 다음 시도가 성공한다고 약속하지 않는 명시적 재시도 동작을 제공하세요. 상위 요청이 실패하면 예약한 크레딧을 반환하지만, 응답에 대사 처리 보류가 표시될 수도 있습니다. 앱이 응답을 완전히 잃었다면 최종 과금 결과는 불확실합니다. 서버에서는 정상적으로 완료되었을 가능성이 있습니다.

공개 /v1/status 경로는 서비스 범위에 관한 고정 안내와 HTTP 처리기의 응답 여부를 제공합니다. 아카이브 검색을 시험하거나 상위 시스템의 정상 상태를 인증하지 않습니다. 운영 판단은 실제 요청 결과를 근거로 하세요. 전체 흐름은 「앱 사용 흐름」으로, 구현 선택은 구현 노트의 「로딩·빈 결과·오류 화면」으로 돌아가 확인할 수 있습니다.