Authentication & Limits

This page explains how to authenticate with Fintatica and the limits that govern API usage. It also includes practical guidance for error handling, pagination sizes, and keeping your integration safe.

Overview

Auth method: API key via header X-API-Key (recommended) or api_key query param (GET-only fallback)

Header priority: If both are present, the header wins and the query param is ignored

Key lifecycle: Keys do not expire; they’re either valid or revoked

Scopes: Single scope (full read access for now)

Base rate limit: 100 requests/minute per API key

Pagination max: per_page up to 1000

Errors: JSON body with a stable shape (see below)

Authentication

Where do I get my API key?

You receive your key during onboarding. Until the dashboard is live, contact support if you need a change (revoke/regenerate).

Heads-up for later: We don’t use token prefixes (like ft_live_…) today. If we introduce them, we’ll note it in the Changelog to help with debugging and key hygiene.

Send the key (preferred: header)

Use an HTTP header—this keeps secrets out of URLs and logs.
(HTTP header names are case-insensitive; we document it as X-API-Key.)

Quick sanity check (curl)

200 OK → token accepted

401 Unauthorized → check header spelling, token value, or contact support to revoke/regenerate

GET-only fallback (query param)

For compatibility, GET endpoints also accept a query param:

?api_key=<YOUR_API_KEY>

For example:

Important: If both header and query param are present, the header takes precedence and the query param is ignored. Prefer the header for security (URLs can end up in logs, proxies, analytics, or browser history).

Key rotation & compromise

Self-serve rotation: Not available yet.

If exposed/compromised: Email support to revoke and issue a new key. Update all deployments to use the new key and redeploy.

Rate Limits

Base policy

100 requests per minute per API key (sustained).

We can adjust limits on request. Heavier endpoints may publish stricter caps on their individual pages if needed.

On 429 (rate limited)

Response uses the standard error body (below).

Headers include when to retry.

Example response body (rate limited):

{
  "success": false,
  "message": "Rate limit exceeded",
  "code": "rate_limited",
  "error_data": {}
}

Rate-limit headers

We return the standard headers so you can pace requests:

X-RateLimit-Limit — your minute-level quota

X-RateLimit-Remaining — requests left in the current window

X-RateLimit-Reset — UNIX timestamp (seconds) when the window resets

Retry-After — seconds to wait before retrying (present on 429)

Best practice: honor Retry-After, implement exponential backoff, and keep a small jitter to avoid thundering herds.

Pagination, Sizes & Concurrency

Pagination model: page / per_page (offset).

Max per_page: 1000.

Recommended per_page: start with 100–500 and adjust based on latency and your rate budget.

Large syncs: iterate pages rather than requesting max-size pages; it’s friendlier to rate limits and reduces retries on transient errors.

Client timeouts: choose a reasonable client timeout (e.g., 30–60s).

Parallelism: Not enforced by the API today; for stability, keep parallel requests proportional to your rate limit and back off on 429/5xx.

Compression & response size: we don’t publish a server-side max right now. If you’re moving a lot of data, prefer incremental paging and persist as you go.

Error Responses

All error responses use JSON with a stable shape:

{
  "success": false,
  "message": "Human-readable message",
  "code": "machine_readable_code",
  "error_data": {}
}

Content-Type: application/json

Typical HTTP statuses: 400–499 for client issues, 500–599 for server-side problems

The list of specific error codes (e.g., unauthorized, rate_limited, invalid_param, not_found) lives in Error Codes.

Security Checklist (recommended)

Keep keys secret: never embed in public frontends or repositories.

Use environment variables (e.g., FT_API_KEY) or your secrets manager.

Prefer the header over api_key query param.

Rotate on suspicion: if a key might be exposed, contact support to revoke and reissue immediately.

Least distribution: limit how many services/people have access to your key.

Log carefully: avoid printing full tokens to logs.

Acceptable Use (interim guidance)

Until our final Terms of Service is published:

Attribution & lineage: when redistributing derived insights externally, cite the official sources (CVM, B3, IBGE, etc.) listed on each endpoint page.

No bulk re-hosting: don’t publicly re-host raw Fintatica API payloads at scale.

Respect rate limits: implement backoff and avoid automated retries that ignore headers.

Fair usage: avoid scraping behavior that attempts to circumvent limits or mimics dozens of clients.

For edge cases (e.g., commercial redistribution of large derived datasets), contact support.

Versioning & Changes

You’re on /v1. We aim to keep changes additive within a version.

Any changes to auth or limits will be announced in the Changelog with reasonable notice.

FAQs

Do tokens expire?
No. They’re valid until revoked.

Can I have multiple keys per account?
Yes. Ask support if you need changes.

Can you raise my limits?
Often, yes—email support with your use case.

Useful links

Status: https://status.fintatica.com.br

Quick Start: how to make your first call and handle pagination

Error Codes: all codes and recovery guidance

Common Params: pagination, filtering, and date conventions

Authentication & Limits

Overview#

Authentication#

Where do I get my API key?#

Send the key (preferred: header)#

Quick sanity check (curl)#

GET-only fallback (query param)#

Key rotation & compromise#

Rate Limits#

Base policy#

On 429 (rate limited)#

Rate-limit headers#

Pagination, Sizes & Concurrency#

Error Responses#

Security Checklist (recommended)#

Acceptable Use (interim guidance)#

Versioning & Changes#

FAQs#

Useful links#