> ## Documentation Index
> Fetch the complete documentation index at: https://hexagraph-docs.voyla.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Hexagraph API: HTTP Error Codes and How to Handle Them

> HTTP error codes returned by the Hexagraph API. Covers 400 Bad Request, 404 Not Found, 429 Too Many Requests, and 500 server errors with example responses.

The Hexagraph API uses standard HTTP status codes to indicate the success or failure of a request. Error responses are returned as JSON objects with descriptive message fields and reset timestamps so your application can programmatically detect and handle failure conditions.

## Error Response Format

All error responses share a consistent JSON structure:

```json theme={null}
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "IP rate limit exceeded (max 30 requests per minute). Please try again in 42 seconds (at 11:40:32 UTC).",
  "reset_in_seconds": 42,
  "reset_at_utc": "2026-08-05T11:40:32.000Z"
}
```

| Field              | Type    | Description                                                              |
| ------------------ | ------- | ------------------------------------------------------------------------ |
| `statusCode`       | integer | The HTTP status code of the error                                        |
| `error`            | string  | Standard HTTP reason phrase corresponding to the status code             |
| `message`          | string  | Human-readable error description with time remaining and reset timestamp |
| `reset_in_seconds` | integer | Seconds remaining until current rate limit window resets                 |
| `reset_at_utc`     | string  | ISO 8601 UTC timestamp when rate limit resets                            |

## HTTP Status Codes

| Code  | Name                  | Description                                                                              |
| ----- | --------------------- | ---------------------------------------------------------------------------------------- |
| `200` | OK                    | Request succeeded. The response body contains the requested data.                        |
| `400` | Bad Request           | Invalid query parameters or malformed request format.                                    |
| `404` | Not Found             | The requested entity ID does not exist in the dataset.                                   |
| `429` | Too Many Requests     | Rate limit exceeded — either 1-minute short-burst IP limit or 24-hour daily query quota. |
| `500` | Internal Server Error | An unexpected server error occurred.                                                     |
| `503` | Service Unavailable   | The service is temporarily unavailable. Retry after a short delay.                       |

## Handling 429 Errors & Rate Limit Headers

A `429 Too Many Requests` response is returned when your IP address exceeds gateway limits:

* **Short-Burst IP Limit**: **30 requests** per 1 minute
* **Daily List/Filter Quota**: **500 requests** per 24 hours
* **Daily Search Quota**: **50 requests** per 24 hours

Every API response includes real-time rate limit headers for client monitoring:

```http theme={null}
X-RateLimit-IP-Limit: 30
X-RateLimit-IP-Remaining: 28
X-RateLimit-IP-Reset-Seconds: 42
X-RateLimit-Daily-Limit: 500
X-RateLimit-Daily-Remaining: 455
```

When you receive a `429` status, inspect `reset_in_seconds` or `X-RateLimit-IP-Reset-Seconds` to determine the exact delay before retrying.

```javascript theme={null}
async function fetchWithRetry(url, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url);
    if (res.status !== 429) return res.json();
    const errorBody = await res.json();
    const waitMs = (errorBody.reset_in_seconds || 5) * 1000;
    await new Promise(r => setTimeout(r, waitMs));
  }
  throw new Error('Rate limit exceeded after retries');
}
```

## Handling 404 Errors

A `404 Not Found` response means the `HX_` ID requested does not exist in the dataset.

**Troubleshooting checklist:**

1. **Verify the `HX_` prefix** — all entity IDs must include the full namespace prefix (e.g. `HX_W3038568908`, `HX_A5028125522`).
2. **Confirm entity type** — ensure the ID matches the endpoint (e.g. author ID `HX_A...` should be sent to `/authors/{id}`, not `/outputs/{id}`).
3. **Inspect GET /rate-limit** — verify your request quota is active.