API 속도 제한 및 모범 사례

모든 Ody API 키는 /v1/api/* 및 MCP 엔드포인트에서 분당 600개의 요청을 처리합니다. 모든 응답에서 RateLimit-* 헤더를 읽고, 429 오류가 발생하면 Retry-After 값으로 백오프하세요.

제한 작동 방식

• 제한은 고정된 60초 창에서 계산되는 키당 제한입니다. 유효한 키가 없는 요청은 대신 IP당 제한됩니다.
• 성공 또는 오류에 관계없이 모든 응답에는 세 가지 표준 헤더가 포함됩니다.
  • RateLimit-Limit — 분당 예산(600).
  • RateLimit-Remaining — 현재 창에 남은 요청 수.
  • RateLimit-Reset — 창이 재설정될 때까지 남은 시간(초).
• 초과 시 오류 코드 resource_exhausted 및 Retry-After 헤더(초)와 함께 429가 반환됩니다. 재시도하기 전에 최소한 해당 시간만큼 기다리세요.

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 23
Retry-After: 23

제한 내에서 유지하기

• RateLimit-Remaining을 주시하고 429 오류에 반응하기보다는 0에 가까워지면 선제적으로 속도를 늦추세요.
• 폴링 대신 웹훅을 사용하세요. message.received와 같은 이벤트에 엔드포인트를 구독하면 Ody가 활동을 푸시합니다. 웹훅 수신 및 서명 확인을 참조하세요. 폴링해야 하는 경우 공유 받은 편지함의 경우 10~30초마다 한 번이면 충분합니다.
• 429 및 5xx 오류 시 지수 백오프 및 지터로 재시도하고 재시도 횟수를 제한하세요. Retry-After가 있는 경우 이를 준수하세요. 전송의 경우 재시도와 Idempotency-Key를 함께 사용하여 이중 전송을 방지하세요. 페이지 매김, 멱등성 및 오류 처리를 참조하세요.
• 데이터를 동기화할 때 작은 페이지를 여러 개 요청하는 대신 더 큰 페이지를 요청하세요(?limit=은 각 엔드포인트의 최대값까지).

키 보안 모범 사례

• 모든 키를 필요한 최소한의 범위로 제한하세요. 생성 시 범위를 선택 해제하세요. 대화만 읽는 대시보드는 conversations:read만 보유해야 합니다. Ody API 키 가져오기를 참조하세요.
• 실제 텍스트가 버그가 될 수 있는 모든 곳에 테스트 키를 사용하세요. 개발 환경 및 CI는 ody_test_… 키로 실행되어 메시지 전송이 시뮬레이션되도록 해야 합니다. 테스트 모드로 안전하게 빌드하기를 참조하세요.
• 통합당 하나의 키를 사용하세요. Zapier, 서버 및 AI 비서에 대해 별도의 키를 사용하면 다른 키를 손상시키지 않고 하나를 폐기할 수 있으며, 설정 → 개발자 API의 "마지막 사용" 열이 의미 있게 유지됩니다.
• 키를 서버 측에 보관하세요. 모바일 앱, 브라우저 JavaScript 또는 공유 문서에 키를 절대 포함하지 마세요. 키를 가진 사람은 누구나 해당 범위 내에서 키 생성자 역할을 할 수 있습니다.
• 순환 및 정리하세요. 더 이상 사용하지 않는 키는 폐기하세요. 일반 텍스트는 한 번만 표시되므로 순환은 새 키를 생성하고 배포한 다음 이전 키를 폐기하는 것을 의미합니다.

관련 문서

• API 개요 및 인증
• 페이지 매김, 멱등성 및 오류 처리
• 웹훅 수신 및 서명 확인
• 테스트 모드로 안전하게 빌드하기