Troubleshooting

​

Authentication errors (401)

​

“Invalid API key format”

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

Authorization: Bearer htext_your_actual_key

​

“Invalid or inactive API key”

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

• Key was deleted or deactivated
• Key was copied incorrectly
• Using a key from wrong environment

1. Check the key in your dashboard
2. Regenerate if needed
3. Ensure no extra whitespace

​

Validation errors (422)

​

“Invalid request parameters”

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "details": [{"field": "font_id", "message": "...", "type": "..."}]
}

​

Common validation issues

​

Rate limits (429)

​

“Rate limit exceeded”

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded for /generate: 500 requests per 1 minute(s)",
  "retry_after": 45
}

1. Read Retry-After header
2. Wait that many seconds
3. Retry the request

​

”Request limit exceeded”

{
  "error": "REQUEST_LIMIT_EXCEEDED",
  "message": "Request limit exceeded: 10000/10000 monthly requests used"
}

​

Output issues

​

Text is clipped/cut off

• Content too long for page size
• Margins too large
• Font size too large for content
• Some fonts and “natural” effects (rotation/variation/indentation) can shift strokes closer to the edge than expected

1. Use font_size: "auto" for automatic fitting
2. Reduce margins
3. Use a larger page size
4. Split text across multiple requests
5. If you use random effects, reduce ranges or disable them for strict layouts

​

Layout looks inconsistent (font/effects)

1. Start with font_id: 1 or 2 for the most predictable output
2. Use /preview with representative text and run multiple previews when randomness is enabled
3. For strict print layouts, disable random effects and keep a larger margin “safe area”

​

Whitespace looks wrong

• Multiple spaces → single space
• Leading/trailing whitespace → removed
• Line breaks preserved (\n)

• Use explicit line breaks (\n)
• Adjust word_spacing parameter

​

Auto font size is too large

{
  "font_size": "auto",
  "max_auto_font_size": 80
}

​

Characters missing or show as boxes

1. Check font’s supported_languages via /fonts
2. Switch to a font that supports your language
3. Font 1 and 10 have broad language coverage

​

Address mode issues

​

”Auto font sizing is not supported for address generation”

{
  "generation_type": "address",
  "font_size": 48
}

​

“Address generation supports maximum 5 lines”

​

”Address generation supports maximum 250 characters”

​

PDF issues

​

PDF looks different from PNG

​

PDF rejected by print service

1. Use appropriate preset (lob, click2mail)
2. For strict preflight, use standard: "pdfx1a"
3. Check bleed/crop settings match vendor requirements

​

PDF has crop marks I don’t want

{
  "pdf": {
    "profile": "document"
  }
}

​

Performance issues

​

Requests are slow

1. Check your network latency
2. Large text takes longer
3. High DPI (600) takes longer
4. Complex effects add time

​

Getting inconsistent results

• enable_word_rotation varies angles
• enable_natural_variation varies letter positions
• enable_random_indentation varies line starts

​

Getting help

1. Capture the X-Request-ID from the response header
2. Note the exact error message and status code
3. Save your request payload (sanitize any PII)
4. Contact support at [email protected]