---
title: "Error Handling"
description: "HTTP status codes, error response format, and troubleshooting guide for the BankSync API."
section: "API"
canonical: "https://banksync.io/docs/api/errors"
---

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.

```json title="Standard Error Response"
{
  "success": false,
  "error": "Human-readable error message"
}
```

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

```json title="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](/docs/api/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.