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.
{
"error": "HTTPS is required"
}HTTP Status Codes
400Bad RequestThe 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
401UnauthorizedThe 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
403ForbiddenThe 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 FoundThe 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
409ConflictThe custom short code is taken.
- "Short code "my-link" is already in use": the custom code is taken
429Too Many RequestsA 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 ErrorReturns "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.
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.
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
- Check that your API key is valid, not expired and not revoked.
- Check that the key has every scope the endpoint needs.
- Send valid JSON with the Content-Type: application/json header.
- Check whether you used up the daily request budget of your plan.
- For 500 errors, wait a moment and retry with exponential backoff.