> Finks API docs. Every page: https://finks.ai/llms.txt. The OpenAPI spec: https://finks.ai/docs/openapi.json.

# Errors

Handle failures and retry the right way.

## The envelope

`details` adds context, such as the field at fault. Log `request_id` and quote it to Finks support.

An error body:

```json
{
  "error": {
    "code": "request.invalid",
    "message": "A sentence saying what was wrong.",
    "request_id": "The id to quote to Finks support",
    "details": { "field": "limit" }
  }
}
```

## Retries

- Only `429 rate_limit.exceeded` sends `Retry-After`. Wait that many seconds, then retry.
- The spend cap reports when it resets in `details.resets_at`. Retrying before then fails.
- `503 content.unresolved` can succeed later. Retry a few times with exponential backoff.
- Never retry a 400 or 401 unchanged: it fails the same way.

## Every code

### Fix the request

- `400 request.invalid`: A parameter or body field is wrong. `details.field` names it when there is one.
- `400 request.out_of_plan`: The request asks for more than your plan allows, such as a page size over the cap, dates before your history window, or `depth: "deep"` (deep search is off on every plan). `details` names the allowance.
- `400 invalid_cursor`: The cursor belongs to another request or account, or the request changed beyond `limit`. Start again from page 1.
- `400 cursor_expired`: The cursor is too old. Start again from page 1.
- `400 invalid_filter`: A screener filter cannot run as written.
- `400 unsupported_subject`: The screener cannot screen that subject.
- `400 unsupported_field_for_subject`: The field does not exist for that subject. GET /v1/screener/fields lists the fields.
- `400 unresolvable_query`: The screen could not be turned into a query the screener can run.
- `413 request.too_large`: The request body is over the 2 MB limit.
- `404 not_found`: No record with that id.
- `410 withdrawn`: The record was withdrawn and is no longer served.

### Check the key or account

- `401 auth.invalid_key`: The key is missing, mistyped or unknown.
- `401 auth.revoked_key`: The key was revoked. Use another key.
- `401 auth.expired_key`: The key expired. Use another key.
- `401 auth.expired_token`: A sign-in token (an MCP app's) is past its 15 minutes. Your client gets a new one; sign in again if it cannot.
- `403 account.not_ready`: The key is valid, but the account's plan limits are not set yet. Contact Finks.
- `501 not_implemented`: Your plan does not include this route or feature, or it is not available yet.

### Wait, or raise a limit

- `429 rate_limit.exceeded`: Too many requests this minute. Wait the seconds in the `Retry-After` header, then retry.
- `429 quota.exceeded`: The account's monthly quota is used up.
- `429 spend_cap.exceeded`: The account's monthly spend cap is reached. `details.resets_at` and `details.limit` say when it resets and what it was.
- `503 content.unresolved`: A read behind the request did not resolve, so the whole request failed instead of answering in part. Retry later.