Skip to main content
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 a descriptive message field so your application can programmatically detect and handle failure conditions. Successful responses always return a 2xx status code.

​
Error Response Format

All error responses share a consistent JSON structure: 
{
  "statusCode": 429,
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "error": "Too Many Requests"
}
FieldTypeDescription
statusCodeintegerThe HTTP status code of the error
messagestringA human-readable description of the error, including remediation hints where applicable
errorstringThe standard HTTP reason phrase corresponding to the status code

​
HTTP Status Codes

CodeNameDescription
200OKRequest succeeded. The response body contains the requested data.
400Bad RequestInvalid query parameters or a malformed request. Check your filter expressions and parameter types.
404Not FoundThe requested entity ID does not exist in the dataset. Verify the OA:ID is correct and properly formatted.
429Too Many RequestsRate limit exceeded — either the 30 requests/min or 1,000 requests/day threshold has been reached.
500Internal Server ErrorAn unexpected error occurred on the server. If this persists, please report it.
503Service UnavailableThe service is temporarily unavailable. This is usually transient — retry after a short delay.

​
Handling 429 Errors

A 429 Too Many Requests response is returned when your IP address exceeds the rate limits applied to the Hexagraph API:
  • 30 requests per minute
  • 1,000 requests per day
When you receive a 429, wait before retrying. The message field in the error body indicates approximately how long to wait. Implementing exponential backoff is strongly recommended to avoid hammering the API and continuing to receive 429 responses: 
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 delay = Math.pow(2, attempt) * 1000;
    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error('Rate limit exceeded after retries');
}
This example retries up to 3 times with delays of 1 s, 2 s, and 4 s between attempts before giving up.
A 429 response does not count against your daily limit quota — it is returned before the request is processed. However, retrying too aggressively will continue to trigger 429 responses and may delay your ability to make successful requests. Always implement a sensible backoff strategy.

​
Handling 404 Errors

A 404 Not Found response means the OA:ID you requested does not exist in the Hexagraph dataset. This can occur for several reasons:
  • The ID was mistyped or truncated.
  • The entity has not yet been indexed in the dataset.
  • The ID belongs to a different entity type than the endpoint you queried (e.g. passing an author ID to /outputs/{id}).
Troubleshooting checklist:
  1. Verify the OA: prefix — all IDs must include the OA: namespace prefix (e.g. OA:W2741809807).
  2. Check URL encoding — when passing an ID as a path parameter, the colon must be percent-encoded as %3A (e.g. OA%3AW2741809807).
  3. Use the resolver endpoint — if you’re unsure of the entity type, try GET /{id} with the full OA:ID. This endpoint resolves across all entity types.
  4. Cross-reference your source — confirm the ID is valid by checking its origin (e.g. an OpenAlex record or a prior API response).
Example 404 response: 
{
  "statusCode": 404,
  "message": "Entity OA:W0000000000 not found.",
  "error": "Not Found"
}