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.

​
Error response format

Error responses return JSON with an error code and message: 
{
  "error": "SOME_ERROR_CODE",
  "message": "Human readable message"
}
The X-Request-ID header is always included on all responses. Some error responses may also include a request_id field in the JSON body, but this is not guaranteed for every endpoint/status code. Use the header value when contacting support.

​
Error code reference

​
401 - Authentication errors

Invalid key format: 
{
  "error": "INVALID_KEY_FORMAT",
  "message": "Invalid API key format"
}
Invalid or inactive key: 
{
  "error": "INVALID_API_KEY",
  "message": "Invalid or inactive API key"
}

​
422 - Validation errors

Validation errors include a details array with field-level issues: 
{
  "error": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "details": [
    {
      "field": "font_id",
      "message": "ensure this value is less than or equal to 90",
      "type": "value_error.number.not_le"
    }
  ]
}

​
429 - Rate limit exceeded

Per-endpoint rate limit: 
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded for /generate: 500 requests per 1 minute(s)",
  "limit": 500,
  "endpoint": "/generate",
  "retry_after": 45
}
Monthly request quota exceeded (generate only): 
{
  "error": "REQUEST_LIMIT_EXCEEDED",
  "message": "Request limit exceeded: 10000/10000 monthly requests used",
  "limit": 10000,
  "used": 10000,
  "period": "monthly",
  "reset_at": "2024-02-01T00:00:00Z"
}

​
500 - Server errors

Server errors include request_id for support: 
{
  "error": "GENERATION_ERROR",
  "message": "Failed to generate image. Please try again later.",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Rate limit headers

When rate limiting applies, responses include:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the window
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetUnix timestamp when the window resets
Retry-AfterSeconds to wait before retrying (on 429 only)

​
Per-endpoint rate limits

Rate limits are enforced per API key:
EndpointLimit
POST /api/v1/generate500 requests / minute
POST /api/v1/preview300 requests / minute
GET /api/v1/fonts100 requests / minute
GET /api/v1/status does not require authentication and is not subject to per-key rate limiting.

​
Request quotas (billing limits)

Accounts may have monthly request quotas. These are enforced on /generate only and return 429 with REQUEST_LIMIT_EXCEEDED.

​
Request IDs

Every response includes the X-Request-ID header. You can supply your own X-Request-ID header on requests — the API will echo it back. This is useful for correlating requests in your logs with support inquiries.