Error Handling

The BankSync API uses conventional HTTP status codes and returns structured JSON error responses to help you diagnose and fix issues quickly.

Error Response Format#

All error responses include a success field set to false and a human-readable error message.

{  "success": false,  "error": "Human-readable error message"}

Validation errors (422) may include additional errors and warnings arrays with detailed information:

{  "success": false,  "error": "Feed configuration is invalid",  "errors": ["sourceConfig.accounts is required for sync feeds"],  "warnings": ["No fieldMappings provided - defaults will be used"]}

HTTP Status Codes#

The API uses standard HTTP status codes to indicate the success or failure of a request.

Troubleshooting#

Common issues and how to fix them.

401: "Invalid or missing API key"#

• Ensure you are passing the key in the X-API-Key header, not as a query parameter.
• Check that the key starts with bsk_ and has not been revoked.
• Make sure there are no extra whitespace or newline characters in the key.

403: "Insufficient permissions"#

• Your API key may not have the required scopes. Check the scopes table in the Authentication guide.
• Check the operation in the API reference and grant each scope it lists.
• The workspace role associated with the key creator may be too low (e.g., viewer trying to write).

403: API key scope required (MCP)#

Since 16 October 2026, an API key created before 4 July 2026 no longer reaches a write or delete tool on the MCP server (triggering a sync, cancelling a job, connecting or removing a bank, creating or deleting feeds, portals, dashboards, enrichments or SimpleFIN access) without the matching scope. Reads are unaffected: an older key still lists and reads everything it always did, and the REST API always checked scopes, so nothing changes there.

The MCP tool error carries the stable code api_key_scope_required in its _meta error code and in the error text, and the message names the exact scope:

This API key needs jobs:write. Keys issued before 2026-07-04 no longer reach writes without the scope: create a key with jobs:write in Settings → Developers → API keys and switch to it (a key's scopes cannot be edited).

Such a key also stops seeing those write tools in tools/list: what is listed is what a call reaches.

• A key's scopes are fixed when it is created. Create a new key carrying the named scope in Settings → Developers → API keys, switch your integration to it, then revoke the old one. See API keys.

404: "Resource not found"#

• Double-check the resource IDs (bankId, accountId, etc.) in your URL path.
• The resource may have been deleted. List the parent resource to verify it exists.
• Ensure you are using the correct workspace: API keys are scoped to the workspace where they were created.

422: "Feed configuration is invalid"#

• Review the errors array in the response for specific field-level issues.
• Use the validate feed endpoint to pre-flight check your configuration before creating or updating.
• Check the warnings array for non-blocking issues that may affect your sync.

429: "Too many requests"#

• You have used your workspace's per-minute API budget. The limit is per workspace and shared by all its API keys; each installed app has its own. A client you cover shares your workspace's limit. See Rate limits.
• Wait the number of seconds in the Retry-After header, then retry the same request. Retrying immediately doesn't help: refused requests also count toward the limit.
• X-RateLimit-Limit shows your plan's requests per minute. If one poll sends more requests than that (for example, one per account), spread them out. See Polling many accounts.
• On the transactions endpoint, a 429 can also mean the bank itself is throttling. The error message says which.
• If you consistently need more headroom, upgrade your plan or contact support.

503: "Consent required"#

• The bank connection requires re-authorization, typically for investment account data.
• Direct the user to the BankSync app to reconnect the bank and grant the required permissions.