> ## 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.

# Error Codes

> Complete reference of all machine-readable error codes.

Always use the `errorCode` field for programmatic error handling. The `message` field is human-readable and may change without notice.

```json theme={null}
{
  "success": false,
  "errorCode": "INVALID_BIRTHDATE",
  "message": "Birthdate must be in YYYY-MM-DD format"
}
```

## Authentication Errors

| Error Code | HTTP Status | Description | Action |
| - | - | - | - |
| `API_KEY_MISSING` | 401 | No `Authorization` header provided | Add `Authorization: Bearer YOUR_KEY` header |
| `API_KEY_INVALID` | 401 | API key not found or deactivated | Check your key in the dashboard |
| `GEOCODE_KEY_MISSING` | 401 | No `HD-Geocode-Key` header on a location-based endpoint | Add the header, or use the [coordinates endpoint](/guides/coordinates-endpoint) |
| `UNAUTHORIZED` | 401 | General authentication failure | Verify your credentials |

## Authorization Errors

| Error Code | HTTP Status | Description | Action |
| - | - | - | - |
| `ACCESS_DENIED` | 403 | Your plan does not include this endpoint | Upgrade to a plan with the required [access tier](/authentication#access-tiers) |
| `ACCOUNT_INACTIVE` | 403 | Account has been deactivated | Contact [support](mailto:info@mail.humandesignapi.nl) |

## Billing Errors

| Error Code | HTTP Status | Description | Action |
| - | - | - | - |
| `CREDITS_EXHAUSTED` | 402 | No credits remaining and overage is disabled | Wait for monthly reset, enable overage, or upgrade your plan |

## Validation Errors

| Error Code | HTTP Status | Description | Action |
| - | - | - | - |
| `INVALID_BIRTHDATE` | 400 | Birthdate is missing or not in `YYYY-MM-DD` format | Use ISO 8601 format: `"1990-01-15"` |
| `INVALID_BIRTHTIME` | 400 | Birthtime is missing or not in `HH:MM` format | Use 24-hour format: `"14:30"` |
| `INVALID_LOCATION` | 400 | Location is empty or shorter than 4 characters | Provide a valid location: `"Amsterdam, The Netherlands"` |
| `INVALID_LATITUDE` | 400 | Latitude is missing, not a number, or outside -90 to 90 | Provide a valid latitude: `52.3676` |
| `INVALID_LONGITUDE` | 400 | Longitude is missing, not a number, or outside -180 to 180 | Provide a valid longitude: `4.9041` |
| `MISSING_REQUIRED_FIELD` | 400 | A required field is missing from the request body | Check the endpoint documentation for required fields |
| `INVALID_REQUEST_BODY` | 422 | Request body is malformed or has structural errors | Ensure valid JSON with correct field types |

## Service Errors

| Error Code | HTTP Status | Description | Action |
| - | - | - | - |
| `GEOCODE_FAILED` | 400 | Google Geocoding service returned an error | Check your geocoding key and try again |
| `GEOCODE_KEY_INVALID` | 400 | Google Geocoding API key is invalid or restricted | Verify your key in Google Cloud Console |
| `GEOCODE_LOCATION_NOT_FOUND` | 400 | Location could not be geocoded | Check spelling, try a more specific location, or use [coordinates](/guides/coordinates-endpoint) |
| `GEOCODE_RATE_LIMITED` | 429 | Google Geocoding rate limit exceeded | Wait and retry, or use the [coordinates endpoint](/guides/coordinates-endpoint) |
| `TIMEZONE_LOOKUP_FAILED` | 500 | Could not determine timezone for the location | Try a nearby major city, or use coordinates with a known timezone |
| `EPHEMERIS_ERROR` | 500 | Astronomical calculation failed | Contact [support](mailto:info@mail.humandesignapi.nl) if this persists |
| `CHART_GENERATION_FAILED` | 500 | Chart generation failed unexpectedly | Contact [support](mailto:info@mail.humandesignapi.nl) if this persists |
| `INTERNAL_ERROR` | 500 | Unexpected server error | Contact [support](mailto:info@mail.humandesignapi.nl) if this persists |

## Rate Limiting

| Error Code | HTTP Status | Description | Action |
| - | - | - | - |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests | Wait for the `Retry-After` header value (in seconds) before retrying |

See [Rate Limiting](/guides/rate-limiting) for limit details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.