Skip to main content

​
Authentication errors (401)

​
“Invalid API key format”

{"error": "INVALID_KEY_FORMAT", "message": "Invalid API key format"}
Cause: API key doesn’t start with htext_. Fix: Ensure your Authorization header is: 
Authorization: Bearer htext_your_actual_key

​
“Invalid or inactive API key”

{"error": "INVALID_API_KEY", "message": "Invalid or inactive API key"}
Causes:
  • Key was deleted or deactivated
  • Key was copied incorrectly
  • Using a key from wrong environment
Fix:
  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": "..."}]
}
Check the details array for specific field errors.

​
Common validation issues

FieldErrorFix
textempty after cleaningProvide non-empty text
font_idnot in range 1-90Use valid font ID
font_sizenot 12-400 or “auto”Use valid size
page_sizeunknown valueUse supported format

​
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
}
Fix:
  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"
}
Fix: Contact sales to increase your quota, or wait for the monthly reset.

​
Output issues

​
Text is clipped/cut off

Causes:
  • 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
Fixes:
  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)

Some fonts have different glyph metrics (letter widths, ascenders/descenders, kerning) and some effects are intentionally random. This can make certain font/settings combinations look slightly different between requests, and in edge cases can push text closer to the margins. Recommendations:
  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

The API normalizes whitespace:
  • Multiple spaces → single space
  • Leading/trailing whitespace → removed
  • Line breaks preserved (\n)
If you need exact spacing:
  • Use explicit line breaks (\n)
  • Adjust word_spacing parameter

​
Auto font size is too large

For short text, auto-fit may produce very large fonts. Fix: Set max_auto_font_size: 
{
  "font_size": "auto",
  "max_auto_font_size": 80
}

​
Characters missing or show as boxes

Cause: Font doesn’t support those characters. Fix:
  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”

Address mode requires manual font sizing. Fix: 
{
  "generation_type": "address",
  "font_size": 48
}

​
“Address generation supports maximum 5 lines”

Fix: Reduce to 5 lines or fewer (count \n separators).

​
”Address generation supports maximum 250 characters”

Fix: Shorten the address text.

​
PDF issues

​
PDF looks different from PNG

Expected: PDF has white background (no transparency). PDFs are rendered on opaque white background for print compatibility.

​
PDF rejected by print service

Fixes:
  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

Fix: Use profile: "document" or a preset that disables marks: 
{
  "pdf": {
    "profile": "document"
  }
}
Or use click2mail preset which disables marks.

​
Performance issues

​
Requests are slow

Normal processing time is 200-800ms. If slower:
  1. Check your network latency
  2. Large text takes longer
  3. High DPI (600) takes longer
  4. Complex effects add time

​
Getting inconsistent results

Natural effects are random by design:
  • enable_word_rotation varies angles
  • enable_natural_variation varies letter positions
  • enable_random_indentation varies line starts
For consistent output, disable these effects.

​
Getting help

If these don’t resolve your issue:
  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]
Include all of the above for fastest resolution.