Finkkle API Error Codes and Troubleshooting Guide

Finkkle One is currently undergoing a major overhaul. The API is disabled until further notice, so live error responses may not match this reference. Finkkle Trends remains accessible. More details soon.

When a Finkkle API request fails, the response includes an error code that identifies the problem. This page lists every error code, explains what triggers it, and tells you how to fix it. For issues not covered here, contact support at [email protected].

API error codes

These errors are returned in API responses with a 4xx or 5xx HTTP status:

Code	HTTP status	Meaning	How to fix
`missing_query`	400	No `q` or `query` parameter in the request	Add a `q` parameter to your request
`query_too_short`	400	Query is below the minimum character length	Ensure the query is at least 2 characters
`missing_api_key`	401	No `Authorization` header present	Add `Authorization: Bearer <key>` to your headers
`invalid_api_key`	401	Key is malformed, expired, or not recognized	Regenerate your key in the Finkkle One dashboard
`api_key_creation_disabled`	403	Key creation is disabled on the platform	Check the Finkkle One dashboard status page
`admin_token_required`	403	This operation requires an admin-level token	Use an admin token or contact support
`search_failed`	500	Upstream search service error	Retry with exponential backoff; contact support if persistent

Service error codes

These errors may appear in service logs or error response bodies for infrastructure-level failures:

Code	Severity	Meaning	Resolution
`ERR_AUTH_FAILED`	High	Authentication failed — invalid or missing API key	Verify your API key is correct and not expired; regenerate if needed
`ERR_UPSTREAM_TIMEOUT`	Medium	An upstream AI or data service did not respond in time	Retry with backoff; check Finkkle status page for ongoing incidents
`ERR_MODERATION_BLOCKED`	Medium	Query or result was flagged by content moderation	Review your `safeSearch` parameter settings; contact support if you believe the block is incorrect
`ERR_CACHE_FAIL`	Low	Cache layer is unavailable; serving from live index	No action needed — results are still served, just without caching

Retry strategy

For transient errors (search_failed, ERR_UPSTREAM_TIMEOUT), use exponential backoff:

async function callWithRetry(url, options, maxAttempts = 4) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const res = await fetch(url, options);
    if (res.ok) return res.json();
    if (res.status >= 400 && res.status < 500) {
      // Client error — do not retry
      const err = await res.json();
      throw new Error(err.code || 'client_error');
    }
    // Server error — wait and retry
    await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 500));
  }
  throw new Error('max_retries_exceeded');
}

Never retry 4xx errors automatically — they indicate a problem with your request that retrying will not fix. Log the error code and surface a meaningful message to your user.

Get help

If you encounter an error not listed here, or need clarification on a service behavior, contact the Finkkle support team: Email: [email protected]
Include: the request ID (from response headers), the error code, a timestamp, and a minimal reproduction if possible.

Platform

API Reference

Account & Plans

Finkkle API Error Codes and Troubleshooting Guide

API error codes

Service error codes

Retry strategy

Get help

​API error codes

​Service error codes

​Retry strategy

​Get help

API error codes

Service error codes

Retry strategy

Get help