사용량 제한

SocFlow API는 모든 사용자에게 안정적인 서비스를 제공하기 위해 사용량 제한을 적용하고 있습니다. 이 가이드에서는 Rate Limiting과 할당량에 대해 알아봅니다.

Rate Limiting

SocFlow API는 요청 빈도를 제한하여 서비스의 안정성을 보장합니다. 각 API 키에는 다음과 같은 제한이 적용됩니다:

Name
요청 제한
Description
분당 최대 60개의 요청을 보낼 수 있습니다.
Name
일일 할당량
Description
하루에 최대 10,000개의 요청을 보낼 수 있습니다.

Rate Limit 헤더

API 응답에는 현재 사용량을 확인할 수 있는 헤더가 포함됩니다:

모든 API 응답에는 Rate Limit 정보가 포함된 헤더가 함께 반환됩니다. 이 정보를 활용하여 요청을 조절할 수 있습니다.

Name
X-RateLimit-Limit
Description
시간당 허용되는 최대 요청 수
Name
X-RateLimit-Remaining
Description
현재 시간 윈도우에서 남은 요청 수
Name
X-RateLimit-Reset
Description
Rate Limit이 리셋되는 시간 (Unix timestamp)

Rate Limit 헤더 예시

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200
Content-Type: application/json

{
  "data": { ... }
}

제한 초과 시

Rate Limit을 초과하면 429 Too Many Requests 상태 코드를 받게 됩니다.

제한을 초과한 요청에는 재시도 가능 시간이 포함된 에러 응답이 반환됩니다. Retry-After 헤더를 확인하여 다음 요청까지 대기해야 하는 시간을 알 수 있습니다.

Rate Limit 초과가 반복되면 일시적으로 API 키가 제한될 수 있습니다. 요청 간격을 적절히 조절하여 안정적으로 API를 사용하세요.

429 에러 응답

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retry_after": 60
  }
}

사용량 조회

현재 API 사용량은 /usage 엔드포인트를 통해 확인할 수 있습니다.

API 사용량 엔드포인트를 호출하면 API 요청 통계와 작업(Job) 사용량을 포함한 상세한 정보를 받을 수 있습니다.

더 높은 사용량 제한이 필요하신 경우 고객 지원으로 문의하세요.

SocFlow 웹 서비스에서 사용한 사용량도 포함됩니다.

curl --location 'https://api.socflow.app/api/v1/usage' \
--header 'X-Secret-Token: {API_KEY}'