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.

Standard Error Response

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

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

Validation Error Response (422)

{
  "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.

Code	Meaning	When It Happens
200	OK	Request succeeded
201	Created	Resource created (POST)
400	Bad Request	Missing required fields, invalid format
401	Unauthorized	Missing or invalid API key / Bearer token
403	Forbidden	Insufficient scopes or role too low
404	Not Found	Resource doesn't exist or was deleted
409	Conflict	Job already in terminal state (cancel)
422	Validation Error	Feed config failed semantic validation
429	Too Many Requests	Rate limit exceeded
500	Internal Error	Server error — contact support
503	Consent Required	Bank requires re-authorization for investment data

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.
Write operations require both the read and write scopes for that resource.
The workspace role associated with the key creator may be too low (e.g., viewer trying to write).

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”

Back off and retry with exponential delay.
Reduce the frequency of your requests or batch operations where possible.
Contact support if you need higher rate limits for your use case.

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.