Errors

GraphQL Errors

GraphQL errors follow the standard GraphQL error specification. The response includes a data field (possibly null) and an errors array:

{
  "data": null,
  "errors": [
    {
      "message": "You must be logged in.",
      "extensions": {
        "code": "UNAUTHENTICATED"
      },
      "path": ["lnkifyConnection"]
    }
  ]
}

Field	Description
message	Human-readable error description
extensions.code	Machine-readable error code
path	Path to the field that caused the error

Common Error Codes

Code	Meaning
UNAUTHENTICATED	Missing or invalid auth (401)
RATE_LIMITED	Too many requests (429)
BAD_USER_INPUT	Invalid or missing input fields
NOT_FOUND	Requested resource does not exist
INTERNAL_SERVER_ERROR	Unexpected server error (500)

HTTP-Level Errors

Status	Meaning	Typical Cause
400	Bad Request	Malformed JSON, missing required fields, invalid input
401	Unauthorized	Missing/invalid JWT or API key
404	Not Found	Slug doesn't exist, resource ID not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unhandled server exception

401 Unauthorized

{
  "errors": [{
    "message": "You must be logged in.",
    "extensions": { "code": "UNAUTHENTICATED" }
  }]
}

404 Not Found (slug redirect)

Plain text response on the redirect endpoint:

HTTP/1.1 404 Not Found
Content-Type: text/plain

Target not found

Partial Success in Bulk Operations

Bulk mutations (createLnkifies, updateLnkifies, deleteLnkifies) return an array where each item reports its own success or failure. One failed item does not abort the batch.

BulkLnkifyResult

{
  "data": {
    "createLnkifies": [
      { "index": 0, "ok": true, "lnkify": { "id": "1", "lnkify": "my-link" }, "error": null },
      { "index": 1, "ok": false, "lnkify": null, "error": "Target URL is required" }
    ]
  }
}

Field	Type	Description
index	Int!	Zero-based position in the input array
ok	Boolean!	Whether this item succeeded
lnkify	lnkify	The created/updated shortlink (null on failure)
error	String	Error message if failed

BulkDeleteResult

{
  "data": {
    "deleteLnkifies": [
      { "index": 0, "id": "1", "ok": true, "error": null },
      { "index": 1, "id": "2", "ok": false, "error": "Not authorized to delete this link" }
    ]
  }
}

MCP Errors

The MCP server returns JSON-RPC error objects:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Authentication required"
  },
  "id": null
}

JSON-RPC Code	HTTP Analog	Meaning
-32001	401	Authentication error
-32000	400	Bad request / invalid input
-32603	500	Internal server error

Error Handling Best Practices

• Always check errors array even when data is present (partial failures in bulk ops)
• Retry on 429 with exponential backoff (see Rate Limits)
• Validate inputs client-side to avoid BAD_USER_INPUT responses
• Handle 401 by refreshing the JWT or checking the API key
• Log extensions.code for debugging — it's more stable than the message string