Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.handtextai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Request headers

​
Authorization (required)

Authorization: Bearer htext_your_api_key
Required for all endpoints except GET /api/v1/status.

​
X-Request-ID (optional)

X-Request-ID: your-unique-request-id
Supply your own request identifier for correlation. The API echoes it back in the response. If omitted, the API generates a UUID. Recommended format: {app-name}-{uuid} or plain UUID.

​
Response headers

​
X-Request-ID

Always present. Contains either your supplied ID or an API-generated UUID. 
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000

​
X-Process-Time

Processing time in seconds (3 decimal places): 
X-Process-Time: 0.523

​
Rate limit headers

Present on authenticated endpoints after the rate-limit check runs:
HeaderDescriptionExample
X-RateLimit-LimitMax requests in window500
X-RateLimit-RemainingRequests left in window499
X-RateLimit-ResetUnix timestamp of reset1704067200
If a /generate request is rejected due to a monthly quota (REQUEST_LIMIT_EXCEEDED), the response may not include X-RateLimit-* headers because quota checks happen before rate limiting.

​
Retry-After

Only on rate-limit 429 responses (RATE_LIMIT_EXCEEDED). Seconds to wait before retrying: 
Retry-After: 45
For quota 429 responses (REQUEST_LIMIT_EXCEEDED), do not retry immediately — wait for the quota reset or increase your quota.

​
Content-Disposition (PDF only)

For PDF responses, includes a suggested filename: 
Content-Disposition: inline; filename="handtext_a4_300dpi.pdf"

​
Handling rate limits

When you receive a 429 response:
  1. Check the JSON error field:
    • RATE_LIMIT_EXCEEDED: read Retry-After (seconds) and retry after waiting
    • REQUEST_LIMIT_EXCEEDED: you’re out of quota — wait for reset or upgrade
  2. Implement exponential backoff for repeated RATE_LIMIT_EXCEEDED responses
Example retry logic (pseudocode): 
def request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            time.sleep(retry_after)
            continue

        return response

    raise Exception("Max retries exceeded")

​
Header summary

HeaderDirectionRequiredDescription
AuthorizationRequestYes*Bearer token authentication
X-Request-IDBothNoRequest correlation ID
X-Process-TimeResponse—Server processing time
X-RateLimit-LimitResponse—Rate limit ceiling
X-RateLimit-RemainingResponse—Remaining requests
X-RateLimit-ResetResponse—Window reset timestamp
Retry-AfterResponse—Wait time (429 only)
Content-DispositionResponse—Filename (PDF only)
*Not required for GET /api/v1/status