Errors

What an error looks like

Every error has the same shape. success is false, and the error object holds the details.

{
  "status": 409,
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Short code \"summer-sale\" is already taken on domain \"clik.is\""
  }
}

• status — the HTTP status, repeated in the body.
• error.code — a fixed name for the problem. Your code can rely on it.
• error.message — a sentence for people. Its words may change, so do not match on it.
• error.details — extra facts. Only some errors send it, and its shape depends on the code.

Every error code

Errors with details

VALIDATION_ERROR

error.message names the first problem. Is a value too long, or not a date? Then details.field holds the field's name, such as title or expires_at. For some fields, error.details maps each field name to its message instead. Tracking ids are one example:

{
  "status": 422,
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "GA4 Measurement ID has an invalid format",
    "details": {
      "ga4_measurement_id": "GA4 Measurement ID has an invalid format"
    }
  }
}

Show each message next to the field it names. If there are no details, show error.message.

DESTINATION_BLOCKED

The destination URL is another link shortener, or a site on Clikso's blocklist. Every URL in the request is checked, including A/B, country and device URLs. Show error.message to the person as it is: it explains which URL was refused. Do not retry the same URL.

{
  "status": 422,
  "success": false,
  "error": {
    "code": "DESTINATION_BLOCKED",
    "message": "This destination URL isn't allowed: \"bit.ly\" is a link shortener, and Clikso links can't point at another short link. Use the final destination URL instead.",
    "details": {
      "destination_url": "This destination URL isn't allowed: \"bit.ly\" is a link shortener, and Clikso links can't point at another short link. Use the final destination URL instead."
    }
  }
}

UPGRADE_REQUIRED

You set a field your plan does not include, such as country rules on Free. error.details says which feature, which field, the lowest plan that has it, and your current plan.

{
  "status": 402,
  "success": false,
  "error": {
    "code": "UPGRADE_REQUIRED",
    "message": "Geo targeting needs the Pro plan or higher.",
    "details": {
      "feature": "geoTargeting",
      "field": "geo_targeting",
      "required_plan": "pro",
      "current_plan": "free"
    }
  }
}

On an update, you can always send a value the link already has, or clear a field. Only a new or changed value is checked.

Adding a folder or tag past your plan's count also returns 402. Then details.feature is folders or tags, details.field is null, and details.limit and details.current give the count.

WORKSPACE_PAYMENT_REQUIRED and WORKSPACE_PAUSED

Every account has one default workspace that's free forever. Each extra workspace needs its own paid plan, and it waits for its first payment before it can be used. An extra workspace is paused (read-only) when its paid plan ends, or when it stops being the default without a paid plan. Both answer with 402 and say which state the workspace is in:

{
  "status": 402,
  "success": false,
  "error": {
    "code": "WORKSPACE_PAUSED",
    "message": "This workspace is read-only. Your short links still work. Add a paid plan or make it your default to make changes.",
    "details": {
      "access_state": "paused",
      "workspace_id": "8a1f2c3d-4b5e-4f60-9a7b-1c2d3e4f5a6b"
    }
  }
}

• WORKSPACE_PAYMENT_REQUIRED — the workspace is waiting for its first payment. Only reading the workspace works (Get workspace details and Get usage). Finish the payment in the dashboard.
• WORKSPACE_PAUSED — the workspace is read-only. It is not the account's default and has no active paid plan. Reads and the click analytics still work, and the short links keep redirecting. Changes need a paid plan, or the owner can make it their default workspace in the dashboard.

workspaces[].access_state in Get workspace details tells you the state before you hit either error: null for a normal workspace. workspaces[].is_default is true when the workspace is its owner's default, which is never paused. It is the owner's flag: a member's API key sees the same value.

USAGE_LIMIT_REACHED

A plan allowance is used up. For the analytics API, error.details.resets_at says when the daily count starts again, at midnight UTC.

{
  "status": 429,
  "success": false,
  "error": {
    "code": "USAGE_LIMIT_REACHED",
    "message": "This workspace has used its 100 analytics API requests for today. The quota resets at 00:00 UTC.",
    "details": {
      "resets_at": "2026-10-10T00:00:00.000Z",
      "limit": 100
    }
  }
}

The monthly link allowance and the daily AI slug allowance send the same code, without details. The Limits page lists every allowance.

When to retry

• 429 RATE_LIMITED — wait the number of seconds in the Retry-After header, then send the same request again.
• 429 USAGE_LIMIT_REACHED — do not retry right away. Wait until the allowance resets, or upgrade.
• 500 INTERNAL_ERROR — retry after a short wait. Double the wait each time, and stop after a few tries.
• Network errors — retry like a 500. For a create, list your links first, so you do not make the same link twice.
• Any other 4xx — do not retry. The same request will fail the same way. Fix it first.

Good to know

• 403 API_KEY_NOT_ALLOWED is a bug in your code, not a key problem. Check that the endpoint is in the API reference.
• A 404 for an id from another workspace is on purpose. The API never says whether that id exists elsewhere.
• Each API reference page lists the errors that endpoint can send.