Request & Response Format

Requests

• All request bodies must be sent as JSON with Content-Type: application/json.
• Unrecognized properties in the request body are stripped automatically. Properties not listed in the parameters table are silently ignored.
• Explicitly disallowed properties trigger a 400 Bad Request error.
• GET endpoints do not accept request bodies.

Successful Responses

Successful responses return a JSON object containing the relevant resource data.POST /v2/shorten returns 201 Created, while POST /v2/shorten/batch returns 200 OK. GET requests return 200 OK.

Error Responses

All error responses conform to a consistent envelope structure:

{
  "statusCode": 400,
  "timestamp": "2026-02-28T02:30:00.000Z",
  "path": "/v2/shorten",
  "method": "POST",
  "message": "Please provide a valid URL"
}

Certain errors include an additional errorType field for programmatic handling (e.g. "BLOCKED", "EXPIRED"). Rate limit errors also include a retryAfter field specifying the cooldown in seconds.