Response Formats

Success Response (201 Created)

When a submission is successfully created, you'll receive a 201 status code with submission details:

{
  "message": "Data inserted successfully",
  "submission": {
    "id": 123,
    "workflow_id": 1,
    "user_id": 5,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Success Response Fields

Field	Description
message	Confirmation message
submission.id	Unique submission identifier
submission.workflow_id	ID of the workflow that processed the submission
submission.user_id	ID of the API user who created the submission
submission.created_at	ISO timestamp when submission was created
submission.updated_at	ISO timestamp when submission was last modified

Error Responses

Validation Error (400 Bad Request)

Occurs when submitted data fails form validation:

{
  "error": "Invalid input data: Validation failed for 'Email': The field must be a valid email address",
  "code": "VALIDATION_ERROR"
}

Common Validation Errors

Error Message	Cause	Solution
"Field 'name' is required"	Missing required field	Add the required field to your request
"Invalid email format"	Email field contains invalid email	Use proper email format (user@domain.com)
"Field exceeds maximum length"	Text too long	Reduce text length to meet field limits
"Invalid date format"	Date in wrong format	Use ISO date format (YYYY-MM-DD)
"Field must be a number"	Non-numeric value in number field	Provide numeric value

Authentication Error (401 Unauthorized)

Occurs when authentication fails:

{
  "error": "Invalid or expired authentication token",
  "code": "TOKEN_INVALID"
}

Authentication Error Codes

Code	Description	Solution
TOKEN_MISSING	No Authorization header	Add Bearer token to request headers
TOKEN_INVALID	Invalid or expired token	Verify token is correct and user is active
USER_INACTIVE	API user account disabled	Contact admin to activate account
GUARD_MISMATCH	Wrong user type	Use API user, not normal account

Authorization Error (403 Forbidden)

Occurs when user lacks permission or workflow is invalid:

{
  "error": "This workflow is no longer valid",
  "code": "WORKFLOW_NOT_AUTHORIZED"
}

Authorization Error Codes

Code	Description	Solution
WORKFLOW_NOT_AUTHORIZED	No permission for workflow	Contact admin to grant workflow access
WORKFLOW_EXPIRED	Workflow past expiration date	Use active workflow or extend expiration
WORKFLOW_INACTIVE	Workflow is disabled	Activate workflow or use different one
INSUFFICIENT_PERMISSIONS	User lacks required roles	Contact admin to assign proper roles

Workflow Not Found (404 Not Found)

Occurs when workflow ID doesn't exist:

{
  "error": "Workflow with ID 999 not found",
  "code": "WORKFLOW_NOT_FOUND"
}

Rate Limit Error (429 Too Many Requests)

Occurs when rate limits are exceeded:

{
  "error": "Daily API request limit exceeded for user",
  "code": "USER_DAILY_LIMIT_EXCEEDED",
  "retry_after": 1642204800
}

Rate Limit Error Codes

Code	Description	Retry Strategy
GLOBAL_MONTHLY_LIMIT_EXCEEDED	System-wide monthly limit	Wait until next month
USER_DAILY_LIMIT_EXCEEDED	User's daily limit reached	Wait until next day
IP_HOURLY_LIMIT_EXCEEDED	IP address hourly limit	Wait one hour or use different IP

Server Error (500 Internal Server Error)

Occurs when server encounters unexpected error:

{
  "error": "Internal server error occurred while processing submission",
  "code": "INTERNAL_ERROR"
}

Response Headers

Rate Limit Headers

All responses include rate limiting information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642204800

Header	Description
X-RateLimit-Limit	Maximum requests allowed in current window
X-RateLimit-Remaining	Number of requests remaining
X-RateLimit-Reset	Unix timestamp when limit resets

Content Headers

Content-Type: application/json
Content-Length: 156

Error Handling Best Practices

1. Check HTTP Status Codes

if (response.status === 201) {
  // Success - process submission data
  console.log('Submission created:', response.data.submission.id);
} else if (response.status === 400) {
  // Validation error - fix data and retry
  console.error('Validation failed:', response.data.error);
} else if (response.status === 401) {
  // Authentication error - check token
  console.error('Authentication failed:', response.data.error);
} else if (response.status === 429) {
  // Rate limit - implement retry with backoff
  console.warn('Rate limited, retry after:', response.data.retry_after);
}

2. Parse Error Messages

function parseValidationError(errorMessage) {
  // Extract field name and specific error
  const match = errorMessage.match(/Validation failed for '(.+?)': (.+)/);
  if (match) {
    return {
      field: match[1],
      message: match[2]
    };
  }
  return { field: 'unknown', message: errorMessage };
}

3. Implement Retry Logic

async function submitWithRetry(data, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await submitData(data);
      return response;
    } catch (error) {
      if (error.response?.status === 429 && i < maxRetries - 1) {
        // Rate limited - wait and retry
        const retryAfter = error.response.data.retry_after || Math.pow(2, i) * 1000;
        await sleep(retryAfter);
        continue;
      } else if (error.response?.status >= 500 && i < maxRetries - 1) {
        // Server error - retry with exponential backoff
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error; // Don't retry for client errors (4xx)
    }
  }
}

4. Log Responses for Debugging

function logApiResponse(response, requestData) {
  const logData = {
    timestamp: new Date().toISOString(),
    status: response.status,
    requestData: requestData,
    responseData: response.data,
    rateLimitRemaining: response.headers['x-ratelimit-remaining']
  };
  
  if (response.status >= 400) {
    console.error('API Error:', logData);
  } else {
    console.log('API Success:', logData);
  }
}

Response Validation

Validate Success Response

function validateSuccessResponse(response) {
  if (!response.data.submission) {
    throw new Error('Invalid success response: missing submission data');
  }
  
  if (!response.data.submission.id) {
    throw new Error('Invalid success response: missing submission ID');
  }
  
  return response.data.submission;
}

Handle Partial Failures

Some complex submissions might partially succeed:

function handlePartialFailure(response) {
  if (response.data.warnings) {
    console.warn('Submission created with warnings:', response.data.warnings);
  }
  
  if (response.data.skipped_fields) {
    console.info('Some fields were skipped:', response.data.skipped_fields);
  }
  
  return response.data.submission;
}

Testing Response Handling

Mock Different Response Types

// Test success response
const mockSuccess = {
  status: 201,
  data: {
    message: "Data inserted successfully",
    submission: { id: 123, workflow_id: 1, user_id: 5 }
  }
};

// Test validation error
const mockValidationError = {
  status: 400,
  data: {
    error: "Validation failed for 'email': Invalid email format",
    code: "VALIDATION_ERROR"
  }
};

// Test rate limit error
const mockRateLimit = {
  status: 429,
  data: {
    error: "Daily limit exceeded",
    code: "USER_DAILY_LIMIT_EXCEEDED",
    retry_after: 86400
  }
};

Understanding these response formats helps you build robust integrations that handle both success and error scenarios gracefully.