> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finkkle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Finkkle API Error Codes and Troubleshooting Guide

> Complete reference for Finkkle API error codes — what each error means, when it occurs, and how to resolve it. Includes both API-level and service-level errors.

<Warning>
  **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.
</Warning>

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 [support@finkkle.com](mailto:support@finkkle.com).

## 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:

```javascript theme={null}
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');
}
```

<Note>
  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.
</Note>

## Get help

If you encounter an error not listed here, or need clarification on a service behavior, contact the Finkkle support team:

**Email:** [support@finkkle.com](mailto:support@finkkle.com)<br />**Include:** the request ID (from response headers), the error code, a timestamp, and a minimal reproduction if possible.