Error Handling

Error Handling

All SDK exceptions extend FormaTexError.

Exception Classes

from formatex import (
    FormaTexError,        # Base — unexpected/server errors
    AuthenticationError,  # 401 — invalid or revoked API key
    CompilationError,     # 422 — LaTeX source has errors
    RateLimitError,       # 429 — too many requests
    PlanLimitError,       # 403 — quota exhausted or plan restriction
)

Full Exception Handler Pattern

from formatex import (
    FormaTexClient, CompilationError, AuthenticationError,
    RateLimitError, PlanLimitError, FormaTexError,
)
import time

with FormaTexClient(api_key) as client:
    try:
        result = client.compile(latex)
        open("out.pdf", "wb").write(result.pdf)

    except CompilationError as e:
        # LaTeX syntax/semantic error
        print(f"Compilation failed: {e}")
        print("--- Compiler log ---")
        print(e.log)          # full pdflatex/xelatex output

    except AuthenticationError:
        # Key is invalid, revoked, or missing
        print("Bad API key — check FORMATEX_API_KEY")

    except PlanLimitError:
        # Monthly quota exceeded or feature not on current plan
        print("Plan limit hit — upgrade at https://app.formatex.io/billing")

    except RateLimitError as e:
        # Too many requests
        print(f"Rate limited — retry in {e.retry_after}s")
        time.sleep(e.retry_after)
        # then retry...

    except FormaTexError as e:
        # Any other API error (5xx, unexpected)
        print(f"API error {e.status_code}: {e}")

Exception Properties

Exception	Extra attributes
FormaTexError	.status_code, .message, .body (raw response dict)
CompilationError	.log (full compiler output string)
RateLimitError	.retry_after (float, seconds)

Reading the Compiler Log

When you catch CompilationError, always print e.log:

! Undefined control sequence.
l.5 \someUndefinedCommand

This is the raw TeX engine output. The error line number and description are in here.

Network / Timeout Errors

Network failures (DNS, connection refused) raise httpx.ConnectError. Timeouts raise httpx.TimeoutException. These are not FormaTexError — they come from the underlying httpx transport:

import httpx

try:
    result = client.compile(latex)
except httpx.TimeoutException:
    print("Request timed out — consider using async_compile for large documents")
except httpx.ConnectError:
    print("Could not connect to the API")

Using in CI

Raise a non-zero exit code on compilation errors to fail your CI pipeline:

import sys
try:
    client.compile(source)
except CompilationError as e:
    print(e.log, file=sys.stderr)
    sys.exit(1)