Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.humandesignapi.nl/llms.txt

Use this file to discover all available pages before exploring further.

Rate limits protect the API from abuse and ensure fair usage for all consumers.

​
Limits

ScopeLimitKey
Authenticated API (/v1/*, /v2/*)100 requests/minPer API key

​
Response When Limited

When you exceed a rate limit, the API returns:
  • HTTP 429 Too Many Requests
  • Error code: RATE_LIMIT_EXCEEDED
  • Retry-After header: number of seconds to wait before retrying
{
  "timestamp": "2026-03-24T12:00:00.000Z",
  "success": false,
  "message": "Too many requests. Please try again later.",
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "type": "",
  "data": null
}

​
Rate Limit Headers

Every response includes standard rate limit headers per the IETF RateLimit header fields specification:
HeaderDescriptionExample
ratelimit-policyPolicy name, quota (q), window in seconds (w), and partition key (pk)"100-in-1min"; q=100; w=60; pk=:ZGE1M2Y4...:
ratelimitPolicy name, remaining requests (r), and seconds until reset (t)"100-in-1min"; r=99; t=60
Retry-AfterSeconds to wait before retrying (only on 429 responses)30

​
Best Practices

  1. Respect Retry-After — when you receive a 429, wait for the specified number of seconds
  2. Monitor rate limit headers — parse the RateLimit header to check remaining requests and throttle proactively
  3. Use exponential backoff — if retrying, increase delay: 1s, 2s, 4s
  4. Cache results — Human Design charts for the same birth data are deterministic. Cache responses to avoid redundant calls
  5. Batch wisely — if generating multiple charts, space requests evenly rather than bursting