Platform

Errors

The error envelope, error types with HTTP status codes, common error codes, and handling patterns.

Every non-2xx response carries one JSON envelope. type is the broad class (matches the HTTP status), code is the specific machine-readable cause, message is human-readable, and request_id ties the failure to our logs.

Error envelope

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "This API key does not exist or was revoked.",
    "request_id": "req_2kD8fQx1mZ7cW4nY0bT3"
  }
}

Error types

type	Status	Meaning
`invalid_request`	400	The body failed validation, or a parameter is malformed.
`authentication_error`	401	Missing, malformed, revoked key, or an unknown access token.
`permission_error`	403	Authenticated, but the plan or role does not allow this.
`not_found`	404	The referenced object does not exist in this app + environment.
`rate_limit_error`	429	Per-second rate limit or monthly quota exhausted.
`provider_error`	502	An upstream connector failed; usually transient.
`api_error`	500	Unexpected FeelConnect failure. Safe to retry with backoff.

Common codes

code	type	What happened
`missing_api_key`	authentication_error	No `Authorization: Bearer` header.
`invalid_api_key`	authentication_error	Key malformed, unknown, or revoked.
`item_not_found`	authentication_error	`access_token` unknown in this app + environment, or item removed.
`live_access_unavailable`	permission_error	Live keys require the Startup plan or above.
`invalid_json`	invalid_request	The body is not valid JSON.
`invalid_field`	invalid_request	A field failed validation; the message names it.
`invalid_access_token`	invalid_request	`access_token` does not look like `fc_at_…`.
`invalid_cursor`	invalid_request	Unknown or foreign sync cursor.
`link_session_expired`	invalid_request	The link token's 30-minute session ended.
`user_mismatch`	invalid_request	`update_item_id` belongs to a different `client_user_id`.
`rate_limit_exceeded`	rate_limit_error	Token bucket empty or monthly quota reached.
`internal_error`	api_error	Unexpected failure; include `request_id` when reporting.

Handling errors

SDKs raise a typed error carrying the envelope. Branch on type for policy (retry, reauth, surface to user) and on code only when you need the precise cause:

import { FeelConnect, FeelConnectError } from "@feelconnect/node";

try {
  const res = await fc.transactions.sync({ access_token: token });
} catch (err) {
  if (err instanceof FeelConnectError) {
    switch (err.type) {
      case "rate_limit_error":
        await backoff(); break;             // respect X-RateLimit-Reset
      case "authentication_error":
        if (err.code === "item_not_found") markItemDisconnected(); break;
      case "provider_error":
      case "api_error":
        scheduleRetry(); break;             // transient
      default:
        log(err.code, err.message, err.requestId); // a bug on our side of the call
    }
  }
}

Error types

type	Status	Meaning
`invalid_request`	400	The body failed validation, or a parameter is malformed.
`authentication_error`	401	Missing, malformed, revoked key, or an unknown access token.
`permission_error`	403	Authenticated, but the plan or role does not allow this.
`not_found`	404	The referenced object does not exist in this app + environment.
`rate_limit_error`	429	Per-second rate limit or monthly quota exhausted.
`provider_error`	502	An upstream connector failed; usually transient.
`api_error`	500	Unexpected FeelConnect failure. Safe to retry with backoff.

Common codes

code	type	What happened
`missing_api_key`	authentication_error	No `Authorization: Bearer` header.
`invalid_api_key`	authentication_error	Key malformed, unknown, or revoked.
`item_not_found`	authentication_error	`access_token` unknown in this app + environment, or item removed.
`live_access_unavailable`	permission_error	Live keys require the Startup plan or above.
`invalid_json`	invalid_request	The body is not valid JSON.
`invalid_field`	invalid_request	A field failed validation; the message names it.
`invalid_access_token`	invalid_request	`access_token` does not look like `fc_at_…`.
`invalid_cursor`	invalid_request	Unknown or foreign sync cursor.
`link_session_expired`	invalid_request	The link token's 30-minute session ended.
`user_mismatch`	invalid_request	`update_item_id` belongs to a different `client_user_id`.
`rate_limit_exceeded`	rate_limit_error	Token bucket empty or monthly quota reached.
`internal_error`	api_error	Unexpected failure; include `request_id` when reporting.

Handling errors

SDKs raise a typed error carrying the envelope. Branch on type for policy (retry, reauth, surface to user) and on code only when you need the precise cause:

import { FeelConnect, FeelConnectError } from "@feelconnect/node";

try {
  const res = await fc.transactions.sync({ access_token: token });
} catch (err) {
  if (err instanceof FeelConnectError) {
    switch (err.type) {
      case "rate_limit_error":
        await backoff(); break;             // respect X-RateLimit-Reset
      case "authentication_error":
        if (err.code === "item_not_found") markItemDisconnected(); break;
      case "provider_error":
      case "api_error":
        scheduleRetry(); break;             // transient
      default:
        log(err.code, err.message, err.requestId); // a bug on our side of the call
    }
  }
}

Search documentation

Error types

Common codes

Handling errors

Error types

Common codes

Handling errors