Error Codes | Plung

API Documentation

Error Codes Reference

A comprehensive reference of all HTTP status codes returned by the Plung API across every endpoint.

Code	Name	Meaning
`200`	OK	The request succeeded. Returned by all GET endpoints on success.
`201`	Created	A new resource was created. Returned by POST /v2/shorten on success.
`400`	Bad Request	The request body is invalid. Consult the `message` field for the specific validation failure: invalid URL format, alias length violation (3-50 chars), alias already taken, reserved alias violation, password length violation (4-100 chars), invalid `expiresIn` value, or a platform-disabled feature.
`401`	Unauthorized	Missing, invalid, or revoked API key. Only returned by v2 endpoints. Check your `Authorization` header — format must be: Bearer your_api_key_here
`403`	Forbidden	You attempted to use a feature that is not available on your current billing plan (e.g. custom aliases on FREE). Upgrade to a higher tier to access.
`404`	Not Found	The requested short code does not exist. Verify the short code in the URL path.
`410`	Gone	The requested short link has expired due to exceeding its maximum clicks threshold or reaching its expiration deadline.
`429`	Too Many Requests	Rate limit or monthly plan limit exceeded. If it is a per-minute limit, wait for the 60-second window reset. If it is a monthly quota, wait until the first of next month or upgrade your tier.
`500`	Internal Server Error	An unexpected server-side error occurred. The error detail is redacted in production for security. Contact support if the issue persists.
`503`	Service Unavailable	The platform is in maintenance mode. Retry after the maintenance window.

Error Response Examples

Standard Validation Error (400):

json

{
  "statusCode": 400,
  "timestamp": "2026-09-29T14:00:00.000Z",
  "path": "/v2/shorten",
  "method": "POST",
  "message": "Please provide a valid URL"
}

Reserved Alias Error (400):

json

{
  "statusCode": 400,
  "timestamp": "2026-09-29T14:00:00.000Z",
  "path": "/v2/shorten",
  "method": "POST",
  "message": "This alias is reserved and cannot be used"
}

Authentication Error (401):

json

{
  "statusCode": 401,
  "timestamp": "2026-09-29T14:00:00.000Z",
  "path": "/v2/shorten",
  "method": "POST",
  "message": "API key required. Pass your key as: Authorization: Bearer <your-key>"
}

Feature Forbidden on Plan (403):

json

{
  "statusCode": 403,
  "timestamp": "2026-09-29T14:00:00.000Z",
  "path": "/v2/shorten",
  "method": "POST",
  "message": "Your current plan does not include this feature."
}

Monthly Limit Exceeded (429):

json

{
  "statusCode": 429,
  "timestamp": "2026-09-29T14:00:00.000Z",
  "path": "/v2/shorten",
  "method": "POST",
  "message": "Monthly API call limit reached."
}

PreviousGET /v2/stats/:shortCode