요청 제한과 안전

이 API는 토큰이 새어 나가더라도 서버를 해치는 데 쓰이지 못하도록 만들어졌습니다. 다음 보호 장치가 모든 요청에 적용됩니다.

• 대량 멘션 금지. API로 보내는 모든 메시지(웹훅 메시지와 태그 포함)에서 @everyone, @here, 임의의 역할 멘션이 막혀 있습니다. 티켓을 열 때는 패널에 설정된 멘션 역할과 티켓을 연 사람만 멘션할 수 있습니다.
• 사칭 금지. 웹훅 표시 이름에 "discord"나 "clyde" 같은 예약어가 들어가면 다른 이름으로 바뀌고, 프로필 사진을 바꿀 때는 올바른 https:// 주소만 쓸 수 있습니다.
• 프리미엄 필요. API는 프리미엄 기능입니다. 구독이 살아 있지 않으면 모든 요청이 402와 premium_required: true를 돌려주고, 새 토큰을 만들거나 교체할 수 없습니다.
• 요청 제한. 토큰마다 작업별로 제한이 걸립니다(예: 티켓 열기 분당 10회, 메시지 보내기 분당 30회, 이름 바꾸기 10분에 2회, 패널 바꾸기 10분에 2회, 패널 수정 분당 10회, 패널 다시 보내기 10분에 4회, 읽기 분당 120회). 제한을 넘기면 429와 초 단위 retry_after 값이 돌아옵니다. 현재 표는 GET /api/token으로 확인하세요.
• 무거운 읽기는 따로 제한합니다. 대화 기록 검색과 HTML 대화 기록 내려받기는 각각 분당 10회, 색인된 전체 대화 기록은 분당 30회로 제한되므로 넉넉한 분당 120회 읽기 한도를 쓰지 않습니다. 검색은 여기에 더해 서버 전체에서 동시에 두 개까지만 돌아가고 정해진 시간을 넘기면 504로 중단되므로, 검색 때문에 티켓 처리가 밀리는 일이 없습니다.
• 열린 티켓 상한. 서버가 열린 티켓 안전 상한에 도달하면 API로는 새 티켓을 열 수 없고, 차단된 사용자를 위한 티켓도 열지 않습니다.
• 최소 권한. 민감한 권한(티켓 메시지 읽기, 대화 기록 보기, 대화 기록 검색, 대화 기록 HTML 내려받기, 태그 사용, 티켓 이름 바꾸기, 패널 관리, 티켓 패널 바꾸기)은 기본적으로 꺼져 있으며 토큰마다 직접 켜야 합니다.
• 지난 기록 읽기는 감사 대상입니다. HTML 대화 기록 전체를 내려받으면 어떤 토큰이 했는지와 함께 서버의 활동 로그에 기록되며, API가 수행하는 모든 변경도 마찬가지입니다.
• 패널은 설정과 계속 연결됩니다. 패널 관리 권한으로는 패널의 겉모습(이름, 임베드, 버튼)만 바꿀 수 있습니다. 채널, 카테고리, 멘션 역할, 양식, 지원팀은 API로 바꿀 수 없습니다.
• 만료와 교체. 토큰에는 만료 시각을 정할 수 있고, 대시보드에서 비활성화하거나 교체할 수 있습니다. 교체하면 이전 비밀 값은 즉시 무효가 됩니다.
• 서버 범위. 토큰은 만들어진 서버 한 곳에서만 동작하며, 모든 요청마다 그 서버가 맞는지 다시 확인합니다.