Skip to main content

​
API Errors

All errors return a JSON body with a statusCode, message, and error field.

​
Error Response Format

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

​
HTTP Status Codes

CodeMeaningCommon cause
400Bad RequestInvalid or missing request fields
401UnauthorizedMissing, expired, or invalid API key / JWT
403ForbiddenInsufficient permissions or plan limit reached
404Not FoundResource does not exist
409ConflictDuplicate resource (e.g. short code already in use)
500Internal Server ErrorSomething went wrong on our end

​
Auth Errors

A 401 is returned when:
  • The Authorization header is missing
  • The API key is expired or revoked
  • A JWT token is invalid or expired
  • An API key is used with an x-workspace-id that doesn’t match the key’s workspace
A 403 is returned when:
  • The authenticated user doesn’t have the required role (e.g. viewer trying to create a link)
  • The workspace has reached its plan limit for the resource being created

​
Handling Errors

const res = await fetch('https://api.linkutm.com/api/v1/links', {
  headers: { Authorization: 'Bearer lk_live_...' },
});

if (!res.ok) {
  const err = await res.json();
  console.error(err.message); // "Link limit reached. Upgrade your plan."
}