API Docs

v1.0

Get API Key

Developers/Errors

Error Codes

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

Error Response Format

All error responses follow this JSON structure:

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'url' field is required",
    "details": {
      "field": "url",
      "reason": "missing"
    }
  }
}

Field	Type	Description
`success`	boolean	Always `false` for errors
`error.code`	string	Machine-readable error code
`error.message`	string	Human-readable error description
`error.details`	object	Additional context (optional)

HTTP Status Codes

400Bad Request

The request body is invalid or missing required fields.

Common causes:

Missing required parameter (e.g., `url` in /shorten)
Invalid URL format
Invalid parameter type (e.g., string instead of number)
JSON parse error in request body

401Unauthorized

Authentication failed or API key is missing.

Common causes:

Missing Authorization header
Invalid API key format
API key has been revoked
API key doesn't exist

403Forbidden

The API key doesn't have permission for this action.

Common causes:

API key missing required scope
Attempting to access another user's resources
Feature not available on your plan
Account suspended

404Not Found

The requested resource doesn't exist.

Common causes:

Invalid link ID
Link has been deleted
Invalid endpoint URL
Resource belongs to another user

409Conflict

The request conflicts with existing data.

Common causes:

Custom short code already exists
Domain already registered
Duplicate resource creation attempt

422Unprocessable Entity

The request is valid but cannot be processed.

Common causes:

Custom code contains invalid characters
URL is blocked or blacklisted
Expiration date is in the past

429Too Many Requests

Rate limit exceeded. Wait before retrying.

Common causes:

Exceeded daily API request limit
Exceeded burst rate limit
Too many requests from same IP

500Internal Server Error

An unexpected error occurred on our servers.

Common causes:

Server-side bug (please report)
Database connection issue
Third-party service failure

503Service Unavailable

The API is temporarily unavailable.

Common causes:

Scheduled maintenance
Server overload
Infrastructure issues

Rate Limit Errors (429)

When you exceed your rate limit, the response includes headers to help you handle the situation:

429 Response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706745600
Retry-After: 3600

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily rate limit exceeded. Resets in 1 hour.",
    "details": {
      "limit": 10000,
      "reset": "2026-02-01T00:00:00Z",
      "retryAfter": 3600
    }
  }
}

See Rate Limits for more details on limits and best practices.

Error Handling Example

Always check for errors in your API responses:

async function createLink(url) {
  const response = await fetch('https://trimlink.co/api/v1/shorten', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer tk_live_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url }),
  });

  const data = await response.json();

  if (!response.ok) {
    // Handle specific error codes
    switch (response.status) {
      case 401:
        throw new Error('Invalid API key');
      case 429:
        const retryAfter = response.headers.get('Retry-After');
        throw new Error(`Rate limited. Retry in ${retryAfter}s`);
      default:
        throw new Error(data.error?.message || 'Unknown error');
    }
  }

  return data.data;
}

Troubleshooting Checklist

1.Check that your API key is valid and not revoked
2.Verify the API key has the required scopes for the endpoint
3.Ensure the request body is valid JSON with correct fields
4.Check if you've exceeded your rate limits
5.For 5xx errors, wait a moment and retry with exponential backoff