Authentication
Tier Overview
Section titled “Tier Overview”Giltiq uses a tiered access model. Most integrations use Tier 1 (API key).
| Tier | Auth required | How to authenticate |
|---|---|---|
| Tier 0: Anonymous trial | None | No header required |
| Tier 1: Free (100/mo) | API key | X-API-Key: gq_live_... |
| Tier 2: Paid (Starter/Business) | API key | Same as Tier 1 |
Anonymous callers (Tier 0) can make 5–10 validation requests without any setup. When that limit is reached, register for a free API key to continue.
API Keys
Section titled “API Keys”API keys are the primary authentication method for all validation requests. Obtain one via POST /v1/register — no email verification required.
Pass your key using either of these methods:
- Header:
X-API-Key: gq_live_... - Bearer:
Authorization: Bearer gq_live_...
API keys start with gq_live_ and are 32 characters long.
Rate Limits
Section titled “Rate Limits”| Plan | Monthly limit | Per-minute limit |
|---|---|---|
| Anonymous (Tier 0) | 5–10 calls | 5 |
| Free | 100 | 10 |
| Starter | 1,000 | 60 |
| Business | 5,000 | 120 |
Usage and Upgrade Headers
Section titled “Usage and Upgrade Headers”Every API response includes headers so your application — or an agent — can self-regulate without a dashboard visit:
| Header | Example | Description |
|---|---|---|
X-Giltiq-Usage | 85/100 | Validations used vs. your plan limit for the current period |
X-Giltiq-Upgrade | https://giltiq.de/pricing/ | Present only when usage exceeds 80% of your limit |
X-Giltiq-Upgrade is omitted below the 80% threshold. When it appears, agents can surface an upgrade prompt to their operator without requiring a manual dashboard check.
See Usage Endpoint for a full usage breakdown via GET /v1/usage.
HTTP Status Semantics
Section titled “HTTP Status Semantics”Giltiq uses three distinct status codes for access boundaries and rate limiting:
| Status | Code | Meaning |
|---|---|---|
401 | ANONYMOUS_LIMIT_REACHED | Anonymous trial limit reached — register for a free API key to continue |
402 | PLAN_LIMIT_REACHED | Monthly plan limit reached — upgrade required to continue |
429 | RATE_LIMITED | Per-minute rate limit exceeded — back off and retry |
401 and 402 are tier boundaries, not errors. They signal that the caller needs to move to the next tier. 429 is transient: wait for the per-minute window to reset (the Retry-After header gives the exact number of seconds).
See Error Handling for the full error code reference.