Standard Response Object
Client, Server SDK, and REST envelopes for Finatic v1 methods.
Finatic uses one wire shape over HTTP, while each SDK exposes the result in the form that best fits its runtime. Use the envelope for your SDK; do not mix Client SDK result.success.data with Server SDK result.data.
Wire REST
1{
2 "trace_id": "trace_123",
3 "success": {
4 "data": {},
5 "meta": {}
6 },
7 "error": null,
8 "warning": []
9}
10On failure, success is null and error contains a safe message plus an optional stable code, HTTP status, and details.
Client SDK envelope
The browser Client SDK returns { success, error, warning } (plus _id on some calls). Session helpers such as getPortalUrl throw instead of returning a data-method envelope.
1const result = await finatic.v1.listAccounts();
2
3if (result.error) {
4 console.error(result.error.code, result.error.message);
5 return;
6}
7
8const accounts = result.success?.data ?? [];
9for (const warning of result.warning ?? []) {
10 console.warn(warning.message);
11}Server SDK envelopes
The Node and Python Server SDKs return { traceId, data, warnings, errors }. Python start_session without a token returns session identifiers directly, so check session.get('session_id') for that helper.
1const result = await finatic.v1.listAccounts();
2
3if (result.errors?.length) {
4 console.error(result.traceId, result.errors);
5 return;
6}
7
8const accounts = result.data ?? [];Warnings
Warnings can accompany successful data. Log or surface them without treating them as request failures.
1for (const warning of result.warning ?? []) {
2 console.warn(warning.code, warning.message);
3}Common status codes
| Status | Meaning | Action |
|---|---|---|
| 200 | Success | Read Client success.data or Server data |
| 400 | Bad request | Check parameters and field names |
| 401 | Unauthorized | Mint a new short-lived Client token or verify the Server API key |
| 403 | Forbidden | Repair grant, scope, or cluster authorization; do not retry unchanged |
| 404 | Not found | Verify the financial accountId and resource ownership |
| 409 | Identity mismatch | Replace a tenant companyAccountId with the financial accountId |
| 422 | Validation failed | Correct the payload from returned field details |
| 429 | Rate limited | Honor Retry-After and back off a safe read |
| 500 / 503 | Transient server failure | Retry only a safe, idempotent read with a bounded backoff |