Error Codes

All Laghav API errors return a consistent JSON body with a machine-readable code, human message, request ID, and docs URL.

Error response shape

error.json

{
  error: "Human-readable message explaining what went wrong",
  code: "MACHINE_READABLE_CODE",
  request_id: "lgh_req_abc123",
  docs_url: "https://docs.laghav.ai/errors/MACHINE_READABLE_CODE"
}

Complete error code reference

HTTP	Code	Description	Resolution
400	`INVALID_MESSAGES`	messages array malformed or empty	Check that messages is a non-empty array of {role, content} objects
400	`MESSAGES_TOO_LARGE`	Combined input > 100K tokens	Chunk your input or reduce context window
400	`INVALID_MODEL`	Unknown model name	See the Supported Models list
400	`INPUT_TOO_LARGE`	Playground input > 5000 chars	Trim input for playground; use /v1/complete for large inputs
401	`UNAUTHORIZED`	Missing Authorization header	Add Authorization: Bearer lgh_live_xxx header
401	`INVALID_KEY`	API key not found	Verify key in dashboard → Settings → API Keys
401	`KEY_REVOKED`	API key was revoked	Create a new key in the dashboard
403	`PLAN_FEATURE_LOCKED`	Feature not on current plan	Upgrade plan; see /pricing
403	`PROTOCOL_BLOCKED`	Request blocked by company protocol	Review your governance protocol rules
403	`BUDGET_EXCEEDED`	Team monthly budget cap reached	Increase budget or wait for monthly reset
429	`RATE_LIMIT_EXCEEDED`	Too many requests per minute	Retry after X-RateLimit-Reset timestamp
429	`MONTHLY_LIMIT_REACHED`	Monthly call quota exhausted	Upgrade plan to restore access
429	`PLAYGROUND_LIMIT_EXCEEDED`	Daily playground limit reached	Sign up for free account (50/day)
502	`PROVIDER_ERROR`	LLM provider returned an error	Check provider status; retry
503	`COMPRESSOR_UNAVAILABLE`	Compression service is down	Set compress: false as fallback; check status.laghav.ai
504	`PROVIDER_TIMEOUT`	LLM provider took > 30s	Retry; may indicate provider outage

Handling errors in Python

errors.py

from laghav import LaghavClient
from laghav.errors import (
    RateLimitError,
    BudgetExceededError,
    PlanFeatureLockedError,
    ProviderError,
    LaghavError,
)
 
client = LaghavClient()
 
try:
    response = client.complete(messages=[...], model="auto")
 
except RateLimitError as e:
    print(f"Rate limited. Retry after: {e.retry_after}s")
 
except BudgetExceededError as e:
    print(f"Team budget exceeded: {e.budget_id}")
    # Notify team admin
 
except PlanFeatureLockedError as e:
    print(f"Feature not on current plan: {e.feature}")
    print(f"Upgrade at: {e.upgrade_url}")
 
except ProviderError as e:
    print(f"LLM provider error: {e.provider} — {e.message}")
    # Retry with exponential backoff
 
except LaghavError as e:
    # All other Laghav errors
    print(f"Code: {e.code}")
    print(f"Message: {e.message}")
    print(f"Request ID: {e.request_id}")
    print(f"Docs: {e.docs_url}")

Rate Limits Supported Models