Reference

Error Codes

All errors return a JSON body with an error object and a standard HTTP status code.

HTTP status codes

Status	Code	Description
`401`	`UNAUTHORIZED`	Missing or invalid X-API-Key header.
`402`	`PAYMENT_REQUIRED`	Insufficient credit balance to process this request.
`413`	`PAYLOAD_TOO_LARGE`	File exceeds the 50 MB size limit.
`422`	`UNPROCESSABLE_ENTITY`	Unsupported file type or malformed request body.
`429`	`RATE_LIMITED`	Rate limit exceeded for this API key over a rolling 60-second window. Body includes `window_seconds`, `tier`, `limit`, and `degraded`; sleep `Retry-After` seconds before retrying. When `degraded: true` the rate limiter itself is temporarily unavailable — retry quickly (no need to wait the full window). When `degraded` is absent or false you actually exceeded your tier quota; sleep `Retry-After` and retry.
`503`	`SERVICE_UNAVAILABLE`	Inference backend unavailable — circuit breaker is open.

Error response format

{
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Insufficient credit balance to process this request."
  }
}

{
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Insufficient credit balance to process this request."
  }
}

Handling errors

from hyperapi import HyperAPIClient

client = HyperAPIClient(api_key="hk_live_your_key_here")

from hyperapi import AuthenticationError, ParseError

try:
    result = client.parse("invoice.pdf")
    print(result["result"]["ocr"])
except AuthenticationError:
    print("Invalid API key")
except ParseError as e:
    print(f"Parse failed: {e.message} (HTTP {e.status_code})")

from hyperapi import HyperAPIClient

client = HyperAPIClient(api_key="hk_live_your_key_here")

from hyperapi import AuthenticationError, ParseError

try:
    result = client.parse("invoice.pdf")
    print(result["result"]["ocr"])
except AuthenticationError:
    print("Invalid API key")
except ParseError as e:
    print(f"Parse failed: {e.message} (HTTP {e.status_code})")