> ## 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.

# Troubleshooting

> Common issues and how to fix them.

## Authentication errors (401)

### "Invalid API key format"

```json theme={null}
{"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"

```json theme={null}
{"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](https://dashboard.handtextai.com)
2. Regenerate if needed
3. Ensure no extra whitespace

***

## Validation errors (422)

### "Invalid request parameters"

```json theme={null}
{
  "error": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "details": [{"field": "font_id", "message": "...", "type": "..."}]
}
```

**Check the `details` array** for specific field errors.

### Common validation issues

| Field       | Error                | Fix                    |
| ----------- | -------------------- | ---------------------- |
| `text`      | empty after cleaning | Provide non-empty text |
| `font_id`   | not in range 1-90    | Use valid font ID      |
| `font_size` | not 12-400 or "auto" | Use valid size         |
| `page_size` | unknown value        | Use supported format   |

***

## Rate limits (429)

### "Rate limit exceeded"

```json theme={null}
{
  "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"

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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 [api@handtextai.com](mailto:api@handtextai.com)

Include all of the above for fastest resolution.