specification: API Commons Rate Limits
specificationVersion: '0.1'
schema: https://raw.githubusercontent.com/api-evangelist/interface-research/main/schema/api-commons.yml#/$defs/RateLimits
provider: Hyundai
providerId: hyundai
generated: '2026-09-13'
method: probed
source: https://developers.hyundai.com/web/v1/hyundai/faqs
created: '2026-05-04'
modified: '2026-09-13'
supersedes: >-
  A 2026-05-04 bulk-sweep scaffold that invented three tiers (10/100/1000 requests per
  minute against free/professional/enterprise plans that Hyundai does not publish) and
  asserted RateLimit-Policy and 503 semantics never observed. Replaced 2026-09-13 with
  what the provider documents and what the live hosts actually return.
tags:
  - Automobiles
  - Connected Vehicles
  - Rate Limiting
  - Quotas
description: >-
  Rate limiting for the Hyundai Developers connected-car API. Hyundai acknowledges a daily
  per-project call cap on development projects in its public FAQ but does not publish the
  number; the number is visible only inside the authenticated service console. The runtime
  signal, however, IS public: both the production host and the public sample-test host
  return X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset on every response,
  undocumented anywhere in the developer portal.
limit_count: 1
headers:
  limit: X-RateLimit-Limit
  remaining: X-RateLimit-Remaining
  reset: X-RateLimit-Reset
  retryAfter: null
  policy: null
  documented: false
  observed: true
  observed_note: >-
    Header casing on the wire is X-Ratelimit-Limit / X-Ratelimit-Remaining /
    X-Ratelimit-Reset. Reset is a Unix epoch seconds value, not a delta.
responseCodes:
  throttled: null
  note: >-
    The status code returned on exhaustion is not documented and was not induced — this
    pass did not deliberately exhaust a public quota. Recorded as unknown rather than
    guessed.
limits:
  - id: sample-test-tier
    name: Public sample-test tier limit
    scope: per-token
    metric: requests
    limit: 100
    window: unknown
    method: probed
    evidence:
      url: https://dev.kr-ccapi.hyundai.com/api_sample/v1/car/status/{carId}/odometer
      date: '2026-09-13'
      status: 200
      headers_observed:
        X-RateLimit-Limit: '100'
        X-RateLimit-Remaining: '98'
        X-RateLimit-Reset: '1789302018'
    note: >-
      Observed on the anonymous sample-test tier, which is fronted by a Tyk gateway. The
      window length is not stated in the headers or the docs; Reset carried an epoch value
      roughly 17 minutes ahead of the request at the time of probing, which is consistent
      with a short rolling window but is not confirmation and is not recorded as one.
undocumented_limits:
  - id: development-project-daily-cap
    scope: per-project
    window: day
    limit: null
    status: acknowledged-but-unpublished
    evidence:
      url: https://developers.hyundai.com/web/v1/hyundai/faqs
      quote_ko: 개발 단계에서의 API 호출량은 프로젝트 단위로 일별 호출 제한량이 있습니다.
      quote_en: >-
        At the development stage there is a per-project daily call limit on API volume.
      status_code: 200
    note: >-
      The FAQ answer points at the development guide for the number, and the development
      guide's API management section describes only which APIs a project is approved for,
      not a quota. The figure appears to live behind the console login. This is a
      provider-fixable documentation gap, not an absence of limits.
production_observation:
  host: https://prd.kr-ccapi.hyundai.com
  date: '2026-09-13'
  probe: GET /api/v1/user/profile with no Authorization header
  status: 401
  headers_observed:
    X-RateLimit-Limit: '0'
    X-RateLimit-Remaining: '0'
    X-RateLimit-Reset: '0'
  note: >-
    The production host emits the same three headers but zeroes them for an unauthenticated
    caller, so the real production ceiling cannot be read anonymously. It is a per-key value
    surfaced only once a token is presented.
policies:
  - name: Avoid excessive calls
    source: https://developers.hyundai.com/web/v1/hyundai/faqs
    description: >-
      The only client-side guidance Hyundai publishes is a request to take care not to
      over-call as a result of incorrect invocation. No backoff strategy, no jitter
      guidance, no burst allowance and no fair-use clause are published.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com