Errors

Last updated March 21, 2026

SynthLink uses standard HTTP status codes. All error responses include a JSON body with an error field describing what went wrong.

Error format

Every error response returns a JSON object with at minimum an error field. Some errors include additional fields such as retry_after. Rate-limit responses also include HTTP headers such as Retry-After and RateLimit.

Error response shape

{
  "error": "Unauthorized"
}

429 — includes retry_after

{
  "error": "Too Many Requests",
  "retry_after": 12
}

Error reference

400Bad Request

Cause

A query parameter has an invalid value — for example, a non-numeric limit or an invalid ISO 8601 date.

Fix

Check the parameter types and allowed values in the endpoint reference.

401Unauthorized

Cause

The X-SYNTHLINK-KEY header is missing, the key is invalid, or the key has expired.

Fix

Verify the header name and value. If the key has expired, request a new one from the main site Request API Key button.

404Not Found

Cause

The requested endpoint path does not exist.

Fix

Check the endpoint path against the API reference. Paths are case-sensitive.

429Too Many Requests

Cause

You have exceeded the rate limit (60 req/min) or the daily limit (1,000 req/day).

Fix

Read the Retry-After header first, then fall back to the retry_after field in the response body. Use the RateLimit headers to inspect the remaining allowance.

500Internal Server Error

Cause

An unexpected error occurred on the server. This is not caused by your request.

Fix

Retry after a short delay. If the error persists, contact support@synth-link.com.

Handling errors in code

Check the HTTP status code before reading the response body. Treat 4xx errors as client errors that require a code fix, and 5xx errors as transient server errors that can be retried.

fetch — basic error handling

const res = await fetch(
  "https://synth-link.com/api/v1/documents?limit=10",
  { headers: { "X-SYNTHLINK-KEY": process.env.SYNTHLINK_KEY } }
);

if (!res.ok) {
  const err = await res.json().catch(() => ({ error: "Unknown error" }));

  if (res.status === 401) throw new Error("Invalid or expired API key");
  if (res.status === 429) {
    const retryAfterHeader = res.headers.get("Retry-After");
    const retryAfter = Number(retryAfterHeader ?? err.retry_after ?? 10);
    const wait = retryAfter * 1000;
    await new Promise((r) => setTimeout(r, wait));
    // retry...
  }
  if (res.status >= 500) throw new Error("Server error — try again later");

  throw new Error(err.error);
}

const data = await res.json();

Note:If you encounter a persistent 500 error, contact support@synth-link.com with the endpoint, parameters, and approximate time of the request.

Was this helpful?

Sources

Changelog