Skip to main content

​
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

FieldTypeDescription
typestringThe category of error (see Error Types below)
keystringSpecific error identifier within the type
messagestringHuman-readable error description
dataobjectAdditional context-specific information
causedByErrorobjectNested error that caused this error

​
HTTP Status Codes

The API maps error types to appropriate HTTP status codes:
Status CodeError KeyDescription
400(default)Bad Request - Invalid input or request
401not_authenticatedUnauthorized - Authentication required
403access_deniedForbidden - Insufficient permissions
404not_foundNot Found - Resource doesn’t exist
429rate_limit_exceededToo Many Requests - Rate limit exceeded
500internalInternal 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"
  }
}