API error codes reference

When an API request fails, LinkStacked returns a JSON error response with a code, message, and details about what went wrong.

4xx Client errors

• 400 Bad Request — your request body is malformed or missing required fields.
• 401 Unauthorized — your API key is missing or invalid.
• 403 Forbidden — your key is valid but doesn't have permission for this action.
• 404 Not Found — the resource ID you referenced doesn't exist or doesn't belong to your account.
• 409 Conflict — the request conflicts with current state (e.g. a domain that's already connected).
• 422 Unprocessable Entity — the request is syntactically valid but logically invalid.
• 429 Too Many Requests — you've exceeded your rate limit. Check the Retry-After header.

5xx Server errors

• 500 Internal Server Error — an unexpected error occurred on our side. Contact support with the requestId.
• 503 Service Unavailable — we're under maintenance. Check status.linkstacked.com.

Error response format

{
  "error": {
    "code": "LINK_NOT_FOUND",
    "message": "No link with ID lnk_xyz was found.",
    "requestId": "req_abc123"
  }
}