Error Handling

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

401 Unauthorized

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

403 Forbidden - Usage Limit

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

400 Bad Request - Invalid URL

Cause: Invalid URL format

{
  "success": false,
  "message": "Invalid URL format"
}

Solution: Ensure URL includes protocol (http:// or https://)

400 Bad Request - Duplicate Code

Cause: Custom code already exists

{
  "success": false,
  "message": "Custom code already exists"
}

Solution: Choose a different custom code

404 Not Found

Cause: Resource doesn’t exist

{
  "success": false,
  "message": "URL not found"
}

Solution: Verify the resource ID is correct

429 Rate Limit Exceeded

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)

Get Started

Error Response Format

HTTP Status Codes

Common Errors

​Error Response Format

​HTTP Status Codes

​Common Errors

Error Response Format

HTTP Status Codes

Common Errors