> ## Documentation Index
> Fetch the complete documentation index at: https://docs.membrane.agency/llms.txt
> Use this file to discover all available pages before exploring further.

# API Errors

# API Error Reference

The Membrane API uses a standardized error format to provide clear, actionable information when requests fail. This guide covers the error structure, types, and common error scenarios.

## Error Response Format

All API errors follow a consistent JSON structure:

```json theme={null}
{
  "type": "error_type",
  "key": "error_key",
  "message": "Human-readable error description",
  "data": {
    // Additional context-specific data
  },
  "causedByError": {
    // Nested error object if this error was caused by another undelrying error
  }
}
```

### Response Fields

| Field           | Type   | Description                                   |
| --------------- | ------ | --------------------------------------------- |
| `type`          | string | The category of error (see Error Types below) |
| `key`           | string | Specific error identifier within the type     |
| `message`       | string | Human-readable error description              |
| `data`          | object | Additional context-specific information       |
| `causedByError` | object | Nested error that caused this error           |

## HTTP Status Codes

The API maps error types to appropriate HTTP status codes:

| Status Code | Error Key             | Description                             |
| ----------- | --------------------- | --------------------------------------- |
| 400         | (default)             | Bad Request - Invalid input or request  |
| 401         | `not_authenticated`   | Unauthorized - Authentication required  |
| 403         | `access_denied`       | Forbidden - Insufficient permissions    |
| 404         | `not_found`           | Not Found - Resource doesn't exist      |
| 429         | `rate_limit_exceeded` | Too Many Requests - Rate limit exceeded |
| 500         | `internal`            | Internal Server Error                   |

## Error Types

### BAD\_REQUEST

**Type:** `bad_request`

Something is wrong with the input received by the API. This includes validation errors, missing required fields, or invalid data formats.

**Common Keys:**

* `not_found` - The requested resource doesn't exist
* `not_authenticated` - Authentication credentials are missing or invalid
* `access_denied` - User lacks permission for this operation
* `already_exists` - Resource with the same identifier already exists
* `rate_limit_exceeded` - Too many requests in a given time period

**Example:**

```json theme={null}
{
  "type": "bad_request",
  "key": "not_found",
  "message": "Connection with id 'conn_123' not found"
}
```

### CONNECTION

**Type:** `connection`

An error related to a Connection's authentication or communication with an external system.

**Common Keys:**

* `connection_is_defunct` - Connection is no longer valid
* `access_token_expired` - OAuth token needs refresh
* `rate_limit_exceeded` - External API rate limit hit

**Example:**

```json theme={null}
{
  "type": "connection",
  "key": "access_token_expired",
  "message": "Access token for Salesforce connection has expired",
  "data": {
    "connectionId": "conn_sf_123",
    "connectorKey": "salesforce"
  }
}
```

### CONFIGURATION

**Type:** `configuration`

Incorrect or broken configuration in flows, actions, or other configurable elements.

**Example:**

```json theme={null}
{
  "type": "configuration",
  "message": "Invalid field mapping: source field 'customer.email' does not exist",
  "data": {
    "fieldMappingId": "fm_123",
    "missingField": "customer.email"
  }
}
```

### CUSTOM\_CODE

**Type:** `custom_code`

Error in custom JavaScript code execution.

**Example:**

```json theme={null}
{
  "type": "custom_code",
  "message": "JavaScript execution error: ReferenceError: variable is not defined",
  "data": {
    "lineNumber": 15,
    "columnNumber": 8,
    "code": "const result = undefinedVariable + 1"
  }
}
```

### CONCURRENCY

**Type:** `concurrency`

Errors related to concurrent operations and resource locking.

**Common Keys:**

* `lock_timeout` - Failed to acquire lock within timeout period

**Example:**

```json theme={null}
{
  "type": "concurrency",
  "key": "lock_timeout",
  "message": "Could not acquire lock for connection within 30 seconds",
  "data": {
    "resourceId": "conn_123",
    "timeoutMs": 30000
  }
}
```

### INTERNAL

**Type:** `internal`

Unexpected internal errors. These are automatically reported to monitoring systems.

**Example:**

```json theme={null}
{
  "type": "internal",
  "message": "An unexpected error occurred. Please try again or contact support.",
  "data": {
    "errorId": "err_xyz789"
  }
}
```