API Conventions & Limits

While using the HitHorizons API, these basic rules apply.

Authentication

All requests need to be authenticated using an API key. The API key is sent in the HTTP header Ocp-Apim-Subscription-Key.

Ocp-Apim-Subscription-Key: your-api-key-here

Response Format

The responses are encoded as JSON objects.

Response data is wrapped in an envelope containing the following fields:

• Success [bool]: Indicates whether the call was successful.
• Error [string]: In case of an error, contains the error description.
• Result: Actual data returned from the API.

Rate Limits

The API usage is subject to several limits for each subscription:

Minute Rate Limit

This limit is applied in a sliding window. This means that before each call, the number of calls in the past 60 seconds needs to be lower than the limit.

Daily API Call Limit

This limit is applied each calendar day and is reset at midnight UTC.

Monthly Limit

This limit is applied each calendar month and is reset at midnight on the 1st of each month.

Yearly Limit

This limit is applied for a one-year-long period which is reset on a date, which is custom for each subscription.

Response After Exceeding the Rate Limit

After exceeding the rate limit, the following response is returned:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 12
X-Rate-Limit-Remaining-Calls: 0
X-HHUSAPI-Rate-Limit-Usage: 30

{
  "statusCode": "429",
  "message": "Rate limit is exceeded. Try again in 12 seconds.",
  "linkText": null,
  "link": null,
  "popupTitle": null,
  "popupMessage": null,
  "popupLinkText": null,
  "popupLink": null,
  "subscriptionId": "5efa324543fd361210d2e76a"
}

The response indicates that the client cannot access the API for a period indicated in the Retry-After header (in seconds). A textual description of the issue is returned in the message field in the response body.

After receiving this response, the message should be displayed to the user. Subsequent requests will succeed once the Retry-After period elapses.

Response After Exceeding Daily, Monthly, or Yearly Limit

After exceeding the daily, monthly, or yearly limit, the following response is returned:

HTTP/1.1 403 Quota Exceeded (monthly)
X-Rate-Limit-Remaining-Calls: 26
X-HHUSAPI-Rate-Limit-Usage: 4
X-HHUSAPI-Limit-Yearly-Reset-Date: 2024-01-01
X-HHUSAPI-Limit-Yearly: 100000
X-HHUSAPI-Limit-Monthly: 10000
X-HHUSAPI-Limit-Daily: 1000
X-HHUSAPI-Usage-Yearly: 41332
X-HHUSAPI-Usage-Monthly: 10000
X-HHUSAPI-Usage-Daily: 135

{
  "statusCode": "403",
  "message": "You have exceeded your HitHorizons monthly API quota.",
  "linkText": "Request Quota Increase »",
  "link": "mailto:sales@hithorizons.com?subject=HitHorizons+API+Quota+Exceeded",
  "popupTitle": "HitHorizons API Quota Exceeded",
  "popupMessage": "You have exceeded your monthly API quota for HitHorizons.",
  "popupLinkText": "Request Quota Increase",
  "popupLink": "mailto:sales@hithorizons.com?subject=HitHorizons+API+Quota+Exceeded",
  "subscriptionId": "5efa324543fd361210d2e76a"
}

Response Details

• The status code is 403 (Forbidden).
• The status message indicates that the quota was exceeded. The message always starts with "Quota Exceeded", with additional information:
  • Quota Exceeded (daily)
  • Quota Exceeded (monthly)
  • Quota Exceeded (yearly)
  • Quota Exceeded (daily trial)

Response Body Fields