Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/org-quicko/linq/llms.txt

Use this file to discover all available pages before exploring further.

linq returns structured JSON errors on every failure path — there are no plain-text error bodies, no HTML error pages, and no empty responses for non-2xx status codes. Every error, from a missing API key to a Zod validation failure, follows the same envelope. This makes it straightforward to write a single error-handling layer in any client and to map response codes to recovery logic without inspecting response bodies by hand.

​
Error Response Shape

All error responses share one envelope defined by the ApiError class in packages/shared/src/errors.ts: 
{
  "error": {
    "code": "not_found",
    "message": "link not found"
  }
}
​
error
object
required
The error container. Always present on non-2xx responses.

​
HTTP Status Codes

CodeMeaningCommon Causes
200OKSuccessful read or update.
201CreatedSuccessful resource creation (POST endpoints).
204No ContentSuccessful delete or purge. No response body.
400Bad RequestRequest body failed Zod schema validation. The details array carries field-level issues.
401UnauthorizedNo API key was sent, the key is unknown, or the key’s expires_at has passed.
403ForbiddenThe key is valid but its role does not meet the operation’s minimum. Also returned when an admin attempts to revoke or downgrade their own key.
404Not FoundThe resource does not exist or is archived. Archived resources are treated as non-existent to callers.
409ConflictThe request is well-formed but conflicts with current state — e.g., a slug already taken on the domain, a domain that still has active links being archived.
429Too Many RequestsRate limit exceeded. Returned when LINQ_API_RATE_LIMIT_PER_MINUTE is configured and the calling key has exceeded it.
500Internal Server ErrorAn unexpected server-side error. The code field will be internal. Check server logs for the full trace.

​
Error Code to Status Mapping

The code string in the error body maps exactly to one HTTP status code:
codeHTTP Status
validation_failed400
unauthorized401
forbidden403
not_found404
conflict409
rate_limited429
internal500

​
Validation Errors (400)

When a request body fails Zod schema validation, the response is 400 Bad Request with code: "validation_failed". The details array contains one entry per failing field, each following the Zod issue format: 
{
  "error": {
    "code": "validation_failed",
    "message": "validation failed",
    "details": [
      {
        "code": "invalid_type",
        "expected": "string",
        "received": "undefined",
        "path": ["destination"],
        "message": "Required"
      },
      {
        "code": "too_big",
        "maximum": 200,
        "type": "string",
        "inclusive": true,
        "path": ["name"],
        "message": "String must contain at most 200 character(s)"
      }
    ]
  }
}
Each issue object includes:
FieldDescription
codeZod issue code, e.g. invalid_type, too_big, too_small, invalid_string.
pathArray of field names identifying where in the body the issue occurred. Nested fields appear as multiple segments, e.g. ["rules", 0, "destination"].
messageHuman-readable description of the violation.
When building a form or CLI tool that calls linq, iterate over details and map each path to a field-level error message. This avoids a round-trip of “what exactly failed?” for your users.

​
Common Error Scenarios

A 409 Conflict is returned when you POST /api/v1/links with a custom slug that is already claimed on that domain — including by an archived link. Archived links retain their slug reservation so they can be restored without being hijacked.
{
  "error": {
    "code": "conflict",
    "message": "slug already taken"
  }
}
To resolve: choose a different slug, or purge the archived link that holds it first.
A 429 Too Many Requests is returned when LINQ_API_RATE_LIMIT_PER_MINUTE is set and the calling key exceeds it. The response includes a Retry-After header indicating when the caller may retry.
{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded"
  }
}
linq intentionally does not trust X-Forwarded-For for rate-limit attribution. If you deploy linq behind a reverse proxy, apply an edge-level rate limit there for public traffic.
Several resources have immutable fields — slug and domain_id on a link, link_id on a QR code, host on a domain. These endpoints use strict body schemas: sending an immutable field is a 400 Bad Request rather than silently ignoring it.
{
  "error": {
    "code": "validation_failed",
    "message": "validation failed",
    "details": [
      {
        "code": "unrecognized_keys",
        "keys": ["slug"],
        "path": [],
        "message": "Unrecognized key(s) in object: 'slug'"
      }
    ]
  }
}
Archived resources return 404 Not Found from all API endpoints — they are treated as non-existent to callers. This applies to archived links, archived domains, and any resource looked up through an archived parent. If you need to work with an archived resource, restore it first via PATCH { "status": "active" } (admin-only), or use the list endpoint with status=archived to discover and manage archived items.

Build docs developers (and LLMs) love

Get started for freeTalk to us