API Errors

This page is a comprehensive reference of all error codes and HTTP status codes returned by the LinkShark API.

Error Code Reference

Code	HTTP Status	Meaning
`SML001`	404	Resource not found. The requested short URL or resource does not exist.
`SML002`	500	Unexpected server error. An internal error occurred on the server.
`SML003`	400	Duplicate short code. The `shortCode` you provided is already in use by another account.
`SML004`	400	Bulk limit exceeded. The `bulkSave` request contains more than 30 records.
`VE001`	400	Validation error. One or more fields failed validation. The `message` field contains details.
`EN001`	500	Encoding error. An error occurred while processing or encoding data.

HTTP Status Code Summary

Status	Meaning	When It Occurs
`200`	OK	Request succeeded. Response body contains the result.
`400`	Bad Request	Validation failed, duplicate short code, or bulk limit exceeded.
`401`	Unauthorized	Missing or invalid `X-API-KEY` header.
`404`	Not Found	Requested resource does not exist.
`429`	Too Many Requests	Rate limit exceeded (10 req/min per key).
`500`	Internal Server Error	Unexpected server-side failure.

Detailed Error Scenarios

Authentication Errors

Authentication failures return plain text responses (not JSON):

Missing API Key:


HTTP/1.1 401 Unauthorized
Content-Type: text/plain


API key is missing

Invalid API Key:


HTTP/1.1 401 Unauthorized
Content-Type: text/plain


Invalid API key

Validation Errors (VE001)

Validation errors return a JSON response envelope with a descriptive message indicating which field(s) failed.

Missing required field:


{
  "response": null,
  "error": {
    "code": "VE001",
    "message": "url: must not be blank"
  }
}

Invalid URL format:


{
  "response": null,
  "error": {
    "code": "VE001",
    "message": "url: must be a valid URL"
  }
}

Short code too short:


{
  "response": null,
  "error": {
    "code": "VE001",
    "message": "shortCode: size must be between 3 and 30"
  }
}

Short code invalid characters:


{
  "response": null,
  "error": {
    "code": "VE001",
    "message": "shortCode: must contain only alphanumeric characters, hyphens, and underscores"
  }
}

Field exceeds max length:


{
  "response": null,
  "error": {
    "code": "VE001",
    "message": "title: size must be between 0 and 255"
  }
}

Duplicate Short Code (SML003)

Returned when you try to create a short URL with a shortCode that already belongs to a different account.


{
  "response": null,
  "error": {
    "code": "SML003",
    "message": "Short code 'my-link' is already in use"
  }
}

Note: If the shortCode belongs to your own account, the API will update the existing record instead of returning an error.

Bulk Limit Exceeded (SML004)

Returned when the shortUrls array in a /link/external/v1/bulkSave request exceeds 30 items.


{
  "response": null,
  "error": {
    "code": "SML004",
    "message": "Bulk save is limited to 30 records per request"
  }
}

Server Errors (SML002 / EN001)

These indicate an internal failure. If you encounter them consistently, contact LinkShark support.

General server error:


{
  "response": null,
  "error": {
    "code": "SML002",
    "message": "An unexpected error occurred"
  }
}

Encoding error:


{
  "response": null,
  "error": {
    "code": "EN001",
    "message": "An error occurred while encoding data"
  }
}

Handling Errors in Your Code

A recommended pattern for handling API errors:


const response = await fetch(
  "https://api.linkshark.xyz/link/external/v1/save",
  {
    method: "POST",
    headers: {
      "X-API-KEY": apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  },
);
 
if (response.status === 401) {
  // Plain text auth error
  const message = await response.text();
  throw new Error(`Authentication failed: ${message}`);
}
 
if (response.status === 429) {
  // Plain text rate limit error
  throw new Error("Rate limit exceeded. Retry after backoff.");
}
 
const data = await response.json();
 
if (data.error) {
  // Structured JSON error
  console.error(`Error ${data.error.code}: ${data.error.message}`);
  throw new Error(data.error.message);
}
 
// Success
return data.response;