Standard Response Object
Client, Server SDK, and REST envelopes for Finatic v1 methods.
Finatic uses one wire shape on HTTP. Each SDK unwraps it differently. Use the envelope that matches the SDK in that tab — do not mix result.success.data with Server result.data.
Wire REST
1{
2trace_id: string,
3success: { data: unknown, meta?: unknown } | null,
4error: { message: string, code?: string, status?: number } | null,
5warning: Array<{ message: string, code?: string }> | null
6 }
7Client SDK (@finatic/client)
Data methods keep { success, error, warning } (plus _id on some calls). Session helpers such as getPortalUrl throw instead of returning an error envelope.
Server SDKs (@finatic/server-node, finatic-server-python)
Data methods return { traceId, data, warnings, errors }. Python start_session without a token is a third shape: check session.get('session_id'), not data.
Warnings
Warnings can appear on a successful read. Log them; they are not failures.
Common status codes
| Status | Meaning | Action |
|---|---|---|
| 200 | Success | Read Client success.data or Server data |
| 400 | Bad request | Check parameters |
| 401 | Unauthorized | Token expired (~90s init) or API key invalid |
| 403 | Forbidden | Grant or cluster missing |
| 404 | Not found | Wrong financial accountId |
| 409 | Identity mismatch | ACCOUNT_ID_TYPE_MISMATCH if you passed companyAccountId |
| 422 | Validation | Fix the payload |
| 429 | Rate limited | Backoff |
| 500 / 503 | Server | Retry with backoff |