Troubleshooting

Common errors, debugging tips, and error reference.

Error handling

from thetokencompany import (
    TheTokenCompany,
    AuthenticationError,
    InvalidRequestError,
    PaymentRequiredError,
    RequestTooLargeError,
    RateLimitError,
    APIError,
)

client = TheTokenCompany(api_key="ttc-...")

try:
    result = client.compress("Your text...")
except AuthenticationError:
    print("Invalid or missing API key")
except InvalidRequestError as e:
    print(f"Bad request: {e}")
except PaymentRequiredError:
    print("Insufficient balance or exceeded debt limit")
except RequestTooLargeError:
    print("Payload too large - split your input")
except RateLimitError:
    print("Too many requests - back off and retry")
except APIError as e:
    print(f"Unexpected error (status {e.status_code}): {e}")

Error reference

Exception	HTTP	Cause
`AuthenticationError`	401	Invalid or missing API key
`InvalidRequestError`	400	Bad parameters. The SDK raises this locally, before sending, for empty text or an aggressiveness outside 0.0-1.0
`APIError`	422	Server-side request validation failed. `detail` is an array, one entry per rejected field
`PaymentRequiredError`	402	Insufficient balance or exceeded debt limit
`RequestTooLargeError`	413	Request payload exceeds size limit
`RateLimitError`	429	Too many requests - back off and retry
`APIError`	503	A dependency the API needs is unavailable
`APIError`	5xx	Unexpected server error

Common issues

Empty text error

The SDK raises InvalidRequestError if you pass empty or whitespace-only text to compress(). Check that your input is not empty before compressing.

Aggressiveness out of range

Aggressiveness must be between 0.0 and 1.0. Values outside this range raise InvalidRequestError.

Timeouts

The default timeout is 30 seconds. For very large inputs, increase it:

client = TheTokenCompany(api_key="ttc-...", timeout=60)

Gzip issues

Gzip is enabled by default. If you're behind a proxy that doesn't support gzip, disable it:

client = TheTokenCompany(api_key="ttc-...", gzip=False)

Getting help

If you're stuck, reach out at rasmus@thetokencompany.com or through the Contact page.