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"
}