Error Codes

The TrimLink API uses standard HTTP status codes to show success or failure.

Error Response Format

Every error response is a JSON object with one error string that explains what went wrong. Read the HTTP status code to tell errors apart. There is no separate error code field.

400 Response
{
  "error": "HTTPS is required"
}

HTTP Status Codes

400Bad Request

The request failed validation. The error string names the first problem found.

  • destinationUrl is missing or is not a valid public URL
  • "HTTPS is required": the destination starts with http:// instead of https://
  • The destination was flagged as unsafe by the URL safety check
  • An ID in the path is not a valid UUID
  • A field is out of range, such as a QR size outside 256 to 2048
  • A folder, tag or domain with that name already exists
401Unauthorized

The request could not be tied to an active API key or account.

  • "Authentication required": no key reached the server
  • "Invalid API key": the key is unknown or mistyped
  • "API key has expired" or "API key has been revoked"
  • "Your account is not active.": the account is suspended or closed
403Forbidden

The key is valid but not allowed to do this.

  • "Missing required scope(s): links:write": the key lacks a scope the endpoint needs
  • "API access is not available on your current plan. Upgrade to Pro or higher."
  • A plan limit was reached, such as links, QR codes, folders or tags. See the example below.
404Not Found

The resource does not exist in your workspace, for example "Link not found". API keys always act on your personal workspace.

  • Wrong ID
  • The resource was deleted
  • The resource belongs to another account
409Conflict

The custom short code is taken.

  • "Short code "my-link" is already in use": the custom code is taken
429Too Many Requests

A rate limit was reached.

  • The daily API request budget of your plan is used up
  • An hourly limit on one action, such as adding domains
500Internal Server Error

Returns "An unexpected error occurred. Please try again."

  • The request body is not valid JSON (this returns 500, not 400)
  • A server fault. Retry with exponential backoff.

Plan Limit Errors (403)

When a plan limit stops a request, the body also carries the plan (tier), the limit, your current count and, for some limits, a limitKey.

403 Response
HTTP/1.1 403 Forbidden

{
  "error": "You can only create 30 folders on your current plan. Upgrade to Growth for 100 folders.",
  "tier": "pro",
  "limit": 30,
  "current": 30
}

Rate Limit Errors (429)

The daily budget is a rolling 24 hour window per account. The response sends no Retry-After or rate limit headers, so back off and retry later.

429 Response
HTTP/1.1 429 Too Many Requests

{
  "error": "Daily API rate limit reached (1000 requests). Resets in 24h.",
  "remaining": 0
}

See Rate Limits for the limits of each plan.

Error Handling Example

Check the status code of every response:

async function createLink(destinationUrl) {
  const response = await fetch('https://trimlink.co/api/v1/links', {
    method: 'POST',
    headers: {
      'X-API-Key': 'tk_live_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ destinationUrl }),
  });

  const body = await response.json();

  if (!response.ok) {
    // Every error body has a string "error" field
    throw new Error(`${response.status}: ${body.error}`);
  }

  return body.data; // { id, shortCode, originalUrl, shortUrl, createdAt }
}

Troubleshooting Checklist

  1. Check that your API key is valid, not expired and not revoked.
  2. Check that the key has every scope the endpoint needs.
  3. Send valid JSON with the Content-Type: application/json header.
  4. Check whether you used up the daily request budget of your plan.
  5. For 500 errors, wait a moment and retry with exponential backoff.