Errors

All API errors return a consistent JSON structure with machine-readable error codes.

Error format

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to start this research job.",
    "request_id": "req_abc123"
  }
}

The request_id is included when available. Include it in support requests for faster debugging.

HTTP status codes

Status	Code	Meaning
400	validation_error	Invalid request body or parameters.
401	unauthorized	Missing or invalid API key.
402	insufficient_credits	No credits remaining. Purchase more at /billing/buy-credits.
404	not_found	Resource not found (job, document, list, or webhook).
409	conflict	Duplicate resource or operation conflict.
422	validation_error	Invalid company URL (private IP, malformed) or invalid parameters.
429	rate_limit_exceeded	Rate limit exceeded. Check the `Retry-After` header.
500	internal_error	Internal server error. Retry with exponential backoff.

SDK error handling

from auggie import (
    AuggieClient, AuggieError,
    AuthenticationError, InsufficientCreditsError,
    NotFoundError, RateLimitError, ValidationError,
)

client = AuggieClient("aug_your_key")
try:
    result = client.research("https://example.com")
except AuthenticationError:
    print("Invalid API key")
except InsufficientCreditsError:
    print("Buy more credits")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Bad request: {e.message}")
except AuggieError as e:
    print(f"Error {e.status_code} [{e.code}]: {e.message}")