Skip to main content
Every TokenPath error has the same shape:
  • code is stable. Branch on it, not on message.
  • details appears only when there is structured context.
  • request_id identifies the request in TokenPath’s logs. It is also returned on every response, successful or not, in the X-Request-ID header. You can send your own X-Request-ID (up to 128 letters, digits, ., _, or -) and TokenPath will use it.

Should I retry?

Authentication

Billing

Validation

422 validation_error means the request body failed validation. details lists each problem with its location:
Common causes:
  • document, question, or answer is missing or empty.
  • A field is over its length limit. See Long documents.
  • offset_encoding is not utf-8, utf-16, or utf-32.
  • spans is [] or null, or a range breaks 0 <= start < end <= len(answer).
  • threshold is outside 0 to 1.

Document size

See Long documents for how windowing works.

Rate limits and capacity

Keyless access initially shares 60 requests per minute per service process across all callers. Keyed limits are 120 attribution requests per minute per key and 240 per account. POST /v1/generate has its own budget of 30 per minute per key and 60 per account. If you need more, email [email protected].

Server errors

Retry these with exponential backoff. Any credits held for the request are returned before the error is sent. If one keeps recurring, email [email protected] with the request_id.

Streaming errors

POST /v1/generate streams its response, so a failure can happen after the 200 status has been sent. Those failures arrive as a final error event with the same code, message, and request_id. Handle both cases:
  • HTTP error status: nothing was generated, and any credit hold was released.
  • error event: generation had already started, so the charge for the input stands.

A retrying client

Getting help

Email [email protected]. It goes straight to the founders. Include the request_id so we can trace exactly what happened.