Error Handling

How to handle errors from the Human Design API.

All v2 error responses use the same response envelope as success responses. This makes error handling consistent and predictable.

Basic Pattern

{
  "timestamp": "2026-03-24T12:00:01.000Z",
  "success": false,
  "message": "Birthdate must be in YYYY-MM-DD format",
  "errorCode": "INVALID_BIRTHDATE",
  "type": "",
  "data": null
}

1. Check success — if false, the request failed
2. Read errorCode — use this for programmatic logic
3. Never parse message — it is human-readable and may change without notice

JavaScript

const response = await fetch("https://api.humandesignapi.nl/v2/charts/simple", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
    "HD-Geocode-Key": "YOUR_GEOCODE_KEY",
  },
  body: JSON.stringify({ birthdate: "1990-01-15", birthtime: "14:30", location: "Amsterdam" }),
});

const result = await response.json();

if (!result.success) {
  switch (result.errorCode) {
    case "CREDITS_EXHAUSTED":
      // Prompt user to upgrade or wait for reset
      break;
    case "RATE_LIMIT_EXCEEDED":
      // Wait and retry after Retry-After header
      break;
    case "API_KEY_INVALID":
      // Re-authenticate
      break;
    default:
      console.error(`API error: ${result.errorCode} — ${result.message}`);
  }
}

HTTP Status Categories

Status	Meaning	Retry?
400	Validation error (bad input)	No — fix the request
401	Authentication failure	No — check your API key
402	Credits exhausted	No — wait for reset, enable overage, or upgrade
403	Access denied (wrong tier or inactive)	No — upgrade plan or contact support
429	Rate limit exceeded	Yes — wait for Retry-After seconds
500	Server error	Yes — retry with backoff, contact support if persistent

Retry Strategy

• Only retry 429 and 500 errors
• Never retry 400, 401, 402, or 403 — these require a change in the request or account
• For 429, use the Retry-After response header (value in seconds)
• For 500, use exponential backoff (1s, 2s, 4s, max 3 retries)

Full Error Code Reference

See Error Codes for the complete list of all error codes with descriptions and recommended actions.