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.
`429`	Too Many Requests	Rate limit or monthly plan limit exceeded. If it is a per-minute limit, wait the `retryAfter` seconds. If it is a monthly limit, wait until `resetDate`.
`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-02-28T02:30:00.000Z",
  "path": "/v2/shorten",
  "method": "POST",
  "message": "Please provide a valid URL"
}

Reserved Alias Error (400):

json

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

Authentication Error (401):

json

{
  "statusCode": 401,
  "message": "API key required. Pass your key as: Authorization: Bearer <your-key>",
  "error": "Unauthorized"
}

Feature Forbidden on Plan (403):

json

{
  "statusCode": 403,
  "message": "This feature requires the INDIE plan or higher.",
  "error": "Forbidden",
  "feature": "passwordProtection",
  "currentPlan": "FREE",
  "upgradeUrl": "https://plung.co/console/user/billing"
}

Monthly Limit Exceeded (429):

json

{
  "statusCode": 429,
  "message": "Monthly API call limit reached.",
  "limit": 2000,
  "resetDate": "2026-04-01",
  "upgradeUrl": "https://plung.co/console/user/billing"
}

PreviousGET /v2/stats/:shortCode