Hexagraph API: HTTP Error Codes and How to Handle Them

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:

{
  "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:

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.

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:

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

Overview

REST Endpoints

GraphQL

Hexagraph API: HTTP Error Codes and How to Handle Them

Error Response Format

HTTP Status Codes

Handling 429 Errors & Rate Limit Headers

Handling 404 Errors

​Error Response Format

​HTTP Status Codes

​Handling 429 Errors & Rate Limit Headers

​Handling 404 Errors

Error Response Format

HTTP Status Codes

Handling 429 Errors & Rate Limit Headers

Handling 404 Errors