Skip to main content
All errors follow a consistent format: 
{
  "error": {
    "code": "INVALID_PASSPORT",
    "message": "Passport not found or has been revoked",
    "status": 404,
    "details": {}
  }
}

​
Error Codes

CodeStatusDescriptionSolution
UNAUTHORIZED401Invalid or missing API keyCheck your Authorization header
FORBIDDEN403Insufficient permissionsVerify your API key has the required scopes
NOT_FOUND404Resource not foundCheck the ID or path
INVALID_PASSPORT404Passport not found or revokedVerify the passport ID and status
RATE_LIMITED429Too many requestsImplement exponential backoff
MODEL_UNAVAILABLE503Selected model is temporarily unavailableUse a different model or retry
EPOCH_ANCHORING_FAILED500Solana anchoring failedWill be retried automatically
RECEIPT_VERIFICATION_FAILED422Receipt verification failedCheck the receipt ID and proof
INVALID_REQUEST400Malformed request bodyCheck required fields
QUOTA_EXCEEDED402Usage quota exceededUpgrade your plan

​
Handling Errors

try {
  const result = await lucid.chat.completions({ ... });
} catch (error) {
  if (error.status === 429) {
    // Rate limited — wait and retry
    await sleep(error.retryAfter * 1000);
    return retry();
  }
  if (error.status === 503) {
    // Model unavailable — try alternative
    return lucid.chat.completions({ model: "claude-3-sonnet", ... });
  }
  throw error;
}