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:

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

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

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

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

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

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

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