Error Handling

Error Response Format

All errors return a consistent JSON format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "request_id": "abc123"
  }
}

Some error types include additional fields (e.g., upgrade_url, register_url) — see the examples below.

Error Codes

HTTP Status	Code	Description
400	INVALID_VAT_ID	VAT ID format is invalid
401	UNAUTHORIZED	Missing or invalid API key
401	ANONYMOUS_LIMIT_REACHED	Anonymous trial ceiling hit; register for a free API key to continue
402	quota_exceeded	Monthly quota exceeded on free tier; upgrade to continue
404	NOT_FOUND	Endpoint or resource not found
429	RATE_LIMITED	Per-minute burst limit exceeded; back off and retry (never returned for monthly quota limits)
500	INTERNAL_ERROR	Unexpected server error
503	SOURCE_UNAVAILABLE	All upstream validation sources unavailable

Anonymous Limit Response

When the anonymous (Tier 0) trial ceiling is reached, the API returns 401 with:

{
  "error": "anonymous_limit_reached",
  "message": "Register for a free API key to continue (100 calls/month, no payment required).",
  "register_url": "https://api.giltiq.de/v1/register"
}

Quota Exceeded Response

When the free-tier monthly quota is exhausted, the API returns 402 with:

{
  "error": "quota_exceeded",
  "message": "Monthly free tier limit reached. Upgrade to continue.",
  "upgrade_url": "https://giltiq.de/pricing/"
}

Tier boundaries never return 429

429 RATE_LIMITED is reserved exclusively for per-minute burst protection. Monthly quota exhaustion always returns 401 anonymous_limit_reached (anonymous) or 402 quota_exceeded (free tier), never 429.

Response Headers

Every response includes usage tracking headers:

• X-Giltiq-Usage — Current usage vs. limit, e.g. 85/100
• X-Giltiq-Upgrade — Upgrade URL (e.g. https://giltiq.de/pricing/); present only when usage exceeds 80% of the plan limit

On 429 responses (per-minute burst limiter only):

• X-RateLimit-Limit — Maximum requests allowed per minute
• X-RateLimit-Remaining — Requests remaining in the current window
• X-RateLimit-Reset — Unix timestamp when the window resets
• Retry-After — Seconds until the per-minute rate limit resets