Skip to main content

​
Error Response Format

All API errors follow a consistent format: 
{
  "success": false,
  "message": "Human-readable error message",
  "error": "Detailed error information (development only)"
}

​
HTTP Status Codes

Status CodeDescription
200Success
201Created successfully
400Bad Request - Invalid input
401Unauthorized - Invalid or missing authentication
403Forbidden - Insufficient permissions or usage limit exceeded
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error

​
Common Errors

Cause: Invalid or missing API key
{
  "success": false,
  "message": "Invalid API key"
}
Solution: Check that your API key is correct and included in the X-API-Key header
Cause: Monthly usage limit exceeded
{
  "success": false,
  "message": "Monthly URL creation limit exceeded",
  "code": "USAGE_LIMIT_EXCEEDED",
  "data": {
    "limit": 100,
    "current": 100,
    "action": "createUrl"
  }
}
Solution: Upgrade your plan or wait until next billing cycle
Cause: Invalid URL format
{
  "success": false,
  "message": "Invalid URL format"
}
Solution: Ensure URL includes protocol (http:// or https://)
Cause: Custom code already exists
{
  "success": false,
  "message": "Custom code already exists"
}
Solution: Choose a different custom code
Cause: Resource doesn’t exist
{
  "success": false,
  "message": "URL not found"
}
Solution: Verify the resource ID is correct
Cause: Too many requests
{
  "success": false,
  "message": "Rate limit exceeded. Please try again later.",
  "retryAfter": 900
}
Solution: Wait for the time specified in retryAfter (seconds)