Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.limitly.dev/llms.txt

Use this file to discover all available pages before exploring further.

The Limitly Next.js SDK provides powerful request validation capabilities to enforce rate limits and usage policies.

​
Basic Validation

Validate a request using the user’s API key: 
import { Limitly } from '@limitly/limitly-nextjs';

const limitly = new Limitly({
  apiKey: process.env.LIMITLY_API_KEY!
});

// Validate a request
const result = await limitly.validation.validate(
  'user_api_key',
  '/api/users',
  'GET'
);

if (result.success) {
  console.log('Request allowed');
} else {
  console.log('Request denied:', result.error);
}

​
API Route Integration

Integrate validation directly into your Next.js API routes: 
// app/api/users/route.ts
import { Limitly } from '@limitly/limitly-nextjs';

const limitly = new Limitly({
  apiKey: process.env.LIMITLY_API_KEY!
});

export async function GET(request: Request) {
  const apiKey = request.headers.get('authorization')?.replace('Bearer ', '');
  
  if (!apiKey) {
    return Response.json({ error: 'API Key required' }, { status: 401 });
  }

  const result = await limitly.validation.validate(
    apiKey,
    new URL(request.url).pathname,
    request.method
  );

  if (!result.success) {
    return Response.json({
      error: 'Rate limit exceeded',
      details: result.details
    }, { status: 429 });
  }

  // Process the request
  return Response.json({ message: 'Success' });
}

​
Validation Response

The validation method returns a detailed response: 
interface ValidateRequestResponse {
  success: boolean;
  error?: string;
  details?: {
    limit: number;
    remaining: number;
    reset: number;
    retryAfter?: number;
  };
}

​
Using withRateLimit Helper

The SDK provides a withRateLimit helper for easier integration: 
// app/api/users/route.ts
import { Limitly } from '@limitly/limitly-nextjs';

const limitly = new Limitly({
  apiKey: process.env.LIMITLY_API_KEY!
});

async function handleGetUsers(request: Request) {
  // Your API logic here
  return Response.json({ users: [] });
}

// Wrap your handler with rate limiting
export const GET = limitly.withRateLimit(handleGetUsers);

​
Custom Error Handling

Customize error responses for rate limit exceeded: 
// app/api/users/route.ts
import { Limitly } from '@limitly/limitly-nextjs';

const limitly = new Limitly({
  apiKey: process.env.LIMITLY_API_KEY!
});

async function handleGetUsers(request: Request) {
  return Response.json({ users: [] });
}

export const GET = limitly.withRateLimit(handleGetUsers, {
  onRateLimitExceeded: (request: Request) => {
    return Response.json({
      error: 'Too many requests',
      message: 'Please try again later'
    }, { status: 429 });
  }
});

​
Validation Options

You can pass additional options to the validation: 
const result = await limitly.validation.validate(
  'user_api_key',
  '/api/users',
  'GET',
  {
    // Custom options
    timeout: 5000,
    retryAttempts: 3
  }
);

​
Error Types

The SDK handles various error scenarios:
  • Invalid API Key: Returns 401 Unauthorized
  • Rate Limit Exceeded: Returns 429 Too Many Requests
  • Network Errors: Returns 500 Internal Server Error
  • Validation Errors: Returns 400 Bad Request

​
Next Steps