gravitational/teleport · warning

tokens quota exceeded. Contact your Teleport administrator

Error message

tokens quota exceeded. Contact your Teleport administrator

What it means

ErrLimitExceeded is returned when Teleport rejects an LLM request because the token quota has been exceeded. It maps to HTTP 429 (StatusTooManyRequests) in StatusCodeFromErr and to the provider's rate-limit error type in provider response mapping (e.g. anthropic.go).

Source

Thrown at lib/srv/app/llm/errors/errors.go:49

	ErrTimeout = errors.New("the request timed out. Try again or use streaming for long responses")
	// ErrBadRequest returned when the request has bad format or invalid fields.
	ErrBadRequest = errors.New("the inference provider rejected the request as invalid. Check the request body for unsupported or invalid fields")
	// ErrCanceled returned when the request is canceled.
	ErrCanceled = errors.New("the request was canceled")
	// ErrUnauthorized returned when the request is unauthorized.
	ErrUnauthorized = errors.New("the inference provider rejected the request due to authentication or authorization configuration. Contact your Teleport administrator")
	// ErrRejected returned when the provider rejects the request.
	ErrRejected = errors.New("the inference provider rejected the request due to usage limits. Contact your Teleport administrator")
	// ErrUnsupported returned when the requested endpoint is not supported.
	ErrUnsupported = errors.New("teleport doesn't support the requested endpoint, please check the list of supported endpoints in the documentation")
	// ErrBadResponse returned when the provider replied the request with an unsupported message or format.
	ErrBadResponse = errors.New("the inference provider returned an unexpected response. Contact your Teleport administrator")
	// ErrConfig returned when the app or app service are misconfigured, requiring admin intervention.
	ErrConfig = errors.New("unable to serve request due to an app configuration error. Contact your Teleport administrator")
	// ErrInternal returned when there is a Teleport processing error (nothing to do with the inference provider).
	ErrInternal = errors.New("unable to serve the request due to an internal error. Contact your Teleport administrator")
	// ErrLimitExceeded returned when Teleport rejects the request due to limit exceeded.
	ErrLimitExceeded = errors.New("tokens quota exceeded. Contact your Teleport administrator")
	// ErrUnknown returned when the handler could not identify the error.
	ErrUnknown = errors.New("the inference provider returned an unexpected error. Contact your Teleport administrator")
)

// ProviderError is an error in the provider format.
type ProviderError struct {
	err    error
	detail string
}

// NewProviderError creates a new provider error with details.
func NewProviderError(err error, detail string, args ...any) *ProviderError {
	if len(args) > 0 {
		detail = fmt.Sprintf(detail, args...)
	}
	return &ProviderError{err, detail}
}

View on GitHub (pinned to 1283425b60)

Solutions

  1. Wait until the quota window resets before issuing more requests
  2. Reduce token usage: shorten prompts, cap max_tokens, batch less
  3. Ask your Teleport administrator to raise the token quota for your role/workspace
  4. Check usage monitoring to identify which users/requests exhausted the budget

Example fix

// before: ignore quota errors, retry blindly
resp, err := client.Complete(ctx, req)
// after: back off on rate-limit errors
resp, err := client.Complete(ctx, req)
if llmerrors.IsLimitExceeded(err) {
  return nil, backoff.Retry(ctx, req, backoff.NewExponential())
}
Defensive patterns

Strategy: validation

Validate before calling

// estimate token usage and check remaining quota before the call
needed := estimateTokens(req.Prompt) + req.MaxTokens
if needed > quota.Remaining(identity) {
  return errors.New("request exceeds remaining token quota")
}

Type guard

func isLimitExceeded(err error) bool {
  return errors.Is(err, llmerrors.ErrLimitExceeded)
}

Try / catch

err := doLLMRequest(ctx, req)
if errors.Is(err, llmerrors.ErrLimitExceeded) {
  // honor Retry-After / back off until quota resets
  return waitForQuotaReset(ctx, identity)
}

Prevention

When it happens

Trigger: A request goes through the quota Reservation path (Reserve) and the token budget for the user/workspace is exhausted; the handler then wraps/rejects with ErrLimitExceeded.

Common situations: Heavy model usage during the billing period, shared quota consumed by a team, or automated scripts issuing many large prompts until the quota reserve is denied.

Related errors

AI-assisted analysis of gravitational/teleport@1283425b60 (2026-09-02). Data as JSON: /api/errors/fe26f41da524a6a4. Report an issue: GitHub.