Metering, Tagging, and Rate Limit Headers Reference

Reference for all request and response headers Tokonomics adds, strips, or passes through — including tagging headers and rate limit signals.

Tokonomics uses HTTP headers to let you attach cost metadata to individual requests and to report back usage signals on every response. Some headers are consumed and stripped by the proxy before the request reaches your provider; others are injected by Tokonomics onto the response before it reaches your application.

Request headers (Tokonomics-specific)

The following headers are consumed by Tokonomics and stripped before the request is forwarded upstream. Use them to attach tagging context that appears in your analytics dashboard and cost reports.

X-Metering-Tags · string

A JSON object of custom key-value pairs you want attached to this request’s cost record. Tags appear in your analytics dashboard and can be used to filter and group spend.

{"team": "growth", "feature": "chatbot"}

X-Feature-Name · string

A shorthand single-feature label for this request. Tokonomics stores this as the feature tag key in your cost record. Use it as a quick alternative to a full X-Metering-Tags object when you only need to track one dimension.

support-bot

X-Tenant-ID · string

Your end customer’s tenant identifier. Tokonomics records this against the request so you can break down LLM costs per customer in your analytics dashboard — useful for SaaS products where you want to understand per-tenant spend.

tenant_abc123

Response headers (added by Tokonomics)

Tokonomics injects the following headers onto every proxied response before returning it to your application.

X-Metering-Latency · string

The round-trip latency (in milliseconds) measured between Tokonomics and the upstream provider for this request. This reflects network and provider processing time only — it does not include time between your application and the Tokonomics proxy.

Example: 342ms

X-RateLimit-Limit · integer

The total number of requests your API key is allowed to make per minute under your current plan.

Example: 60

X-RateLimit-Remaining · integer

The number of requests remaining in the current one-minute rate-limit window for your API key. This value resets every minute.

Example: 47

Pass-through headers

All headers not listed above are forwarded to the upstream provider unchanged. This includes, but is not limited to:

• Authorization (your provider API key)
• Content-Type
• anthropic-version
• anthropic-beta
• Any other provider-specific headers your request requires

You do not need to do anything special to pass provider auth headers through — Tokonomics transparently relays them, stripping only the Tokonomics-specific headers described above.

Rate limiting

When you exceed your plan’s per-minute request limit or hit a hard spending cap, Tokonomics returns an HTTP 429 Too Many Requests response instead of forwarding the request to the upstream provider.

The 429 response includes a Retry-After header that tells you exactly how many seconds to wait before retrying:

HTTP/1.1 429 Too Many Requests
Retry-After: 14
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Content-Type: application/json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded your request rate limit. Retry after 14 seconds."
  }
}

Your application should handle 429 responses by reading the Retry-After value and pausing before retrying the request. Most HTTP client libraries support this natively via retry middleware.

You can use both X-Metering-Tags and X-Feature-Name in the same request — they are not mutually exclusive. When both are present, Tokonomics merges them: X-Feature-Name is stored as the feature key inside the tags object, alongside any other keys you provide in X-Metering-Tags.

curl https://tokonomics.ca/proxy/openai/chat/completions \
  -H "Authorization: Bearer mk_your_key" \
  -H "X-Metering-Tags: {\"team\": \"growth\", \"env\": \"production\"}" \
  -H "X-Feature-Name: support-bot" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hi"}]}'

This records the cost entry with tags {"team": "growth", "env": "production", "feature": "support-bot"}.