Skip to main content

​
Overview

The CardClan Integration API uses standard HTTP status codes and provides detailed error messages to help you troubleshoot issues quickly. This guide covers common errors, their causes, and how to handle them effectively in your applications.

​
HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:
  • 200 OK - Request successful, data returned - 201 Created - Resource created successfully (e.g., card sent, configuration created)
  • 400 Bad Request - Invalid request parameters or missing required fields - 401 Unauthorized - Invalid or missing authentication credentials - 404 Not Found - Requested resource doesn’t exist or user doesn’t have access - 409 Conflict - Resource conflict (e.g., integration configuration already exists)
  • 500 Internal Server Error - Unexpected server error - 502 Bad Gateway - Temporary server issue - 503 Service Unavailable - Service temporarily unavailable

​
Error Response Format

All error responses follow a consistent structure: 
{
  "error": "Bad Request",
  "message": "Card ID is required",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}
​
error
string
Human-readable error type corresponding to the HTTP status
​
message
string
Detailed error message explaining what went wrong
​
statusCode
number
HTTP status code for the error
​
timestamp
string
ISO 8601 timestamp when the error occurred

​
Common Errors and Solutions

​
Authentication Errors

Cause: Missing Authorization header in your requestSolution: Include the Bearer token header
// ❌ Missing header
fetch('/api/integration/workspaces')

// ✅ Correct header
fetch('/api/integration/workspaces', {
  headers: {
    'Authorization': 'Bearer your-integration-key'
  }
})
Cause: Authorization header present but token value is emptySolution: Ensure your integration key is properly set
// ❌ Empty token
const token = process.env.CARDCLAN_API_KEY; // undefined

// ✅ Check token exists
const token = process.env.CARDCLAN_API_KEY;
if (!token) {
  throw new Error('CARDCLAN_API_KEY environment variable not set');
}
Cause: Integration key is invalid or has been regeneratedSolution: Generate a new integration key from CardClan dashboard
// Check if key is valid format (UUID)
function isValidIntegrationKey(key) {
  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
  return uuidRegex.test(key);
}

​
Validation Errors

Cause: Missing card parameter in request payloadSolution: Include the card ID in your request
// ❌ Missing card ID
{
  "integrationId": "60f7b2b5b8f4a20015a4f5a7",
  "mergeTags": [{"name": "John", "email": "[email protected]"}]
}

// ✅ Include card ID
{
  "card": "60f7b2b5b8f4a20015a4f5a5",
  "integrationId": "60f7b2b5b8f4a20015a4f5a7",
  "mergeTags": [{"name": "John", "email": "[email protected]"}]
}
Cause: Missing integrationId parameterSolution: Create integration configuration first, then use the returned ID
// Create integration configuration first
const configResponse = await fetch('/api/integration/config', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}` },
  body: JSON.stringify({
    userId: 'user-id',
    workspaceId: 'workspace-id',
    cardId: 'card-id'
  })
});

const config = await configResponse.json();
const integrationId = config.data._id;

// Now use integration ID in send request
await sendCard({ integrationId, ... });
Cause: Missing or invalid mergeTags parameterSolution: Provide merge tags as a non-empty array
// ❌ Missing merge tags
{
  "card": "card-id",
  "integrationId": "integration-id"
}

// ❌ Empty array
{
  "card": "card-id",
  "integrationId": "integration-id",
  "mergeTags": []
}

// ✅ Valid merge tags
{
  "card": "card-id",
  "integrationId": "integration-id",
  "mergeTags": [
    {
      "name": "John Doe",
      "email": "[email protected]"
    }
  ]
}
Cause: Missing workspace query parameter when fetching cardsSolution: Include workspace ID in the query string
// ❌ Missing workspace parameter
fetch('/api/integration/cards', { method: 'POST' })

// ✅ Include workspace parameter
fetch('/api/integration/cards?workspace=60f7b2b5b8f4a20015a4f5a4', {
  method: 'POST'
})

​
Resource Errors

Cause: Card ID doesn’t exist or user doesn’t have permission to access itSolution: Verify the card exists and belongs to your workspace
// First, get available cards for your workspace
const cardsResponse = await fetch(`/api/integration/cards?workspace=${workspaceId}`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

const cards = await cardsResponse.json();
const availableCardIds = cards[0].choices.map(card => card.id);

if (!availableCardIds.includes(cardId)) {
  throw new Error(`Card ${cardId} not found in workspace`);
}
Cause: Trying to create an integration configuration for a card that already has oneSolution: Get the existing configuration instead
try {
  // Try to create new configuration
  const config = await createIntegrationConfig(cardId, workspaceId, userId);
  return config.data._id;
} catch (error) {
  if (error.status === 409) {
    // Configuration exists, get it instead
    const existingConfig = await getIntegrationConfigByCardId(cardId);
    return existingConfig._id;
  }
  throw error;
}
Cause: Trying to use an integration ID that doesn’t existSolution: Create the integration configuration first
async function ensureIntegrationConfig(cardId, workspaceId, userId) {
  try {
    // Try to get existing configuration
    return await getIntegrationConfigByCardId(cardId);
  } catch (error) {
    if (error.status === 409) {
      // Doesn't exist, create it
      const config = await createIntegrationConfig(cardId, workspaceId, userId);
      return config.data;
    }
    throw error;
  }
}

​
Next Steps

Now that you have covered the error handling:
  1. Explore examples
  2. Explore the API reference for detailed endpoint documentation