Errors

The envelope

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

{
  "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.