Authentication

How to obtain and use Pi API keys, understand rate-limit headers, and handle authentication errors.

API keys

Pi issues API keys through Unkey, which handles rate limiting and metering. Your key has the format:

pi_live_...

Never embed API keys in client-side code, browser bundles, or public repositories. Use keys only on trusted server-side backends, workers, or CLI tools.

Sending your key

Include your key as a Bearer token on every request:

Authorization: Bearer <your_api_key>
Content-Type: application/json

Pi does not support query-string authentication or cookie-based auth.

Rate-limit headers

Every authenticated response includes these headers so you can manage your request budget:

Header	Description
X-Request-Id	Unique trace id in the format req_pi_<uuid>. Include this in all support requests.
X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Requests remaining before you hit the limit
X-RateLimit-Reset	Unix timestamp (seconds) when the current window resets

When X-RateLimit-Remaining reaches 0, subsequent requests return 429 Too Many Requests until the window resets.

Authentication error codes

Authentication failures return a structured error envelope:

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_authorization_header",
    "message": "Missing Authorization header. Use Bearer <api_key>.",
    "request_id": "req_pi_9a8b7c6d"
  }
}

Code	HTTP status	Meaning
missing_authorization_header	401	No Authorization header was sent
invalid_api_key	401	The key was malformed or has been revoked
rate_limit_exceeded	429	Too many requests in the current window

Always log request_id from the error envelope when debugging. Include it when contacting Pi support.

Idempotency

Add an Idempotency-Key header to POST requests to prevent duplicate side effects and duplicate billing on retries:

Idempotency-Key: <unique-client-generated-key>

Behavior:

• If you retry the same key with the same body, Pi may replay the original response.
• If you reuse the same key with a different body, Pi returns 409 idempotency_key_mismatch.

Use a UUID or a deterministic hash of the request inputs as your idempotency key so that accidental retries from network errors are safe to replay.

Idempotency-Key support varies by endpoint. Consult individual endpoint docs to confirm support before relying on it.