Knowledge Base

Here you'll find essential information about message handling, guides, and answers to common questions.

Errors

Authentication Errors

Invalid API Key (2002)

json

{
  "code": 2002,
  "message": "Invalid API key",
  "detail": "The API key provided is invalid or has been revoked. Please check your credentials.",
  "docs": "https://docs.harbourshare.com/errors/2002"
}

Missing API Key (2001)

json

{
  "code": 2001,
  "message": "Missing API key",
  "detail": "No API key was provided. Include your key in the Authorization header.",
  "docs": "https://docs.harbourshare.com/errors/2001"
}

Validation Errors

Overview

Our API provides comprehensive validation error handling to help you identify and correct issues with your requests. When a request fails validation, the API returns a detailed error response containing:

A global error code and message indicating that validation failed.
A list of specific validation errors, each detailing the problem with a particular field.

This documentation explains the structure of validation error responses and details each possible validation error, including how to resolve them.

Error Response Format

json

{
  "code": 3001,
  "message": "Invalid request",
  "detail": "The request payload failed validation",
  "docs": "https://docs.harbourshare.com/errors/3001",
  "errors": [
    {
      "path": "field_values.email.value",
      "code": "email",
      "message": "Must be a valid email address.",
      "value": "invalid.email@",
      "internal_message": "Field 'Email' (ID: email) received an invalid email format.",
      "resolution": "Ensure the email follows the standard format (e.g., user@domain.com).",
      "docs": "https://docs.harbourshare.com/errors/validation/email"
    },
    {
      "path": "field_values.birth_date.value",
      "code": "invalid_date_format",
      "message": "'Birth Date' must be in the format YYYY-MM-DD.",
      "value": "31-12-2022",
      "internal_message": "Field 'Birth Date' (ID: birth_date) received an invalid date value: 31-12-2022. Expected format is YYYY-MM-DD.",
      "resolution": "Provide a valid date in the format YYYY-MM-DD (e.g., 2023-01-01).",
      "docs": "https://docs.harbourshare.com/errors/validation/date-format"
    }
  ]
}

Error Response Fields

Field	Type	Description
`code`	`integer`	General error code indicating the type of error (e.g., 3001 for validation errors).
`message`	`string`	Brief summary of the error.
`detail`	`string`	Detailed explanation of what went wrong.
`docs`	`string`	URL linking to detailed documentation about the error.
`errors`	`array`	List of specific validation errors encountered.

Validation Error Fields

Field	Type	Description
`path`	`string`	Location of the invalid field within the request payload (e.g., field_values.email.value).
`code`	`string`	Unique code identifying the type of validation error.
`message`	`string`	Human-readable message suitable for displaying to end users.
`value`	`any`	The invalid value provided.
`internal_message`	`string`	Detailed technical message for developers.
`resolution`	`string`	Steps the user can take to fix the error.
`docs`	`string`	URL linking to documentation about the specific validation error.

Validation Error Types

Below are the validation error types that can be returned by the API, along with their codes, messages, internal messages, resolutions, and documentation links.

Required Field Error
- Code: required
- Message: "field_label is a required field and must be provided."
- Internal Message: "Field field_label (ID: field_id) is required but no value was provided."
- Resolution: "Provide a valid value for field_label before submitting."
Invalid Email Format
- Code: email
- Message: "Must be a valid email address."
- Internal Message: "Field field_label (ID: field_id) received an invalid email format."
- Resolution: "Ensure the email follows the standard format (e.g., user@domain.com)."
Minimum Length Error
- Code: min_length
- Message: "field_label must be at least min_length characters long."
- Internal Message: "Field field_label (ID: field_id) is shorter than the minimum required length of min_length characters."
- Resolution: "Provide a value for field_label that is at least min_length characters long."
Invalid Date Format
- Code: invalid_date_format
- Message: "field_label must be in the format YYYY-MM-DD."
- Internal Message: "Field field_label (ID: field_id) received an invalid date value: value. Expected format is YYYY-MM-DD."
- Resolution: "Provide a valid date in the format YYYY-MM-DD (e.g., 2023-01-01)."
Checkbox Validation Errors
a. Not a List
- Code: checkbox_not_list
- Message: "Must be a list of selected options."
- Internal Message: "Expected list, got type."
- Resolution: "Provide field_label as a list of option labels."
b. No Options Defined
- Code: checkbox_no_options
- Message: "No valid options are defined for this field."
- Internal Message: "No options defined in field configuration."
- Resolution: "Contact support—field_label has no options configured."
c. Duplicate Selections
- Code: checkbox_duplicate
- Message: "field_label contains duplicate selections: 'Option 1', 'Option 3'."
- Internal Message: "Field field_label (ID: field_id) contains duplicate selections: Option 1 (ID: opt1), Option 3 (ID: opt3). Each option can only be selected once."
- Resolution: "Remove duplicate values from your selection. Each option can only be selected once."
d. Invalid Option
- Code: checkbox_invalid_option
- Message: "field_label contains invalid options: 'Invalid1', 'Invalid2'."
- Internal Message: "Field field_label (ID: field_id) contains invalid options. Valid options are: Option 1 (ID: opt1), Option 2 (ID: opt2), Option 3 (ID: opt3)."
- Resolution: "Select only from the available options: Option 1, Option 2, Option 3."
e. Maximum Items Allowed
- Code: checkbox_max_allowed
- Message: "field_label allows maximum of max_items selections."
- Internal Message: "Field field_label (ID: field_id) has selected_count selections; maximum allowed is max_items."
- Resolution: "Select no more than max_items options from the list."
f. Minimum Items Required
- Code: checkbox_min_required
- Message: "Must select at least min_items options."
- Internal Message: "Selected selected_count options; minimum required is min_items."
- Resolution: "Select at least min_items options from: remaining_options."
Image Validation Errors
a. Invalid Image Type
- Code: image_type
- Message: "Must be a valid image file (e.g., JPG, PNG)."
- Internal Message: "Image index must be JPG or PNG format."
- Resolution: "Ensure the image is either JPG or PNG."
b. Invalid Format
- Code: invalid_format
- Message: "Invalid format."
- Internal Message: "Image index has invalid base64 format: missing content."
- Resolution: "Ensure the image is properly base64 encoded with a valid header."
c. Image Size Exceeded
- Code: image_size
- Message: "Total size of images exceeds the allowed limit."
- Internal Message: "Total size of images exceeds 10MB limit. Actual size: actual_size MB."
- Resolution: "Reduce the total size of images to be under 10MB."
Number Validation Error
- Code: invalid_number
- Message: "field_label must be a valid number."
- Internal Message: "Field field_label (ID: field_id) received an invalid number value: value."
- Resolution: "Provide a numeric value for this field (e.g., 123 or 45.67)."

Error Handling Best Practices

Parse All Errors: Multiple validation errors may be returned in a single response. Process all errors before resubmitting.

javascript

function handleValidationErrors(message) {
  if (message.errors) {
    const fieldErrors = message.errors.reduce((acc, err) => {
      acc[err.path] = {
        message: err.message,
        resolution: err.resolution,
      };
      return acc;
    }, {});

    displayErrorsToUser(fieldErrors);
  }
}

Use Appropriate Messages: Show message to end users and log internal_message for debugging.
Implement Progressive Enhancement: Use client-side validation with the same rules to provide immediate feedback, but always validate on the server as well.
Preserve User Input: When displaying errors, don't clear the form - let users correct their mistakes without starting over.
Link to Documentation: Use the docs links in message responses to provide access to detailed validation rules and examples.

Guides

Migrating from V1 to V2 coming soon

We're currently preparing a comprehensive migration guide to help you smoothly transition from API v1 to v2. The guide will include:

Detailed comparison of v1 and v2 endpoints
Step-by-step migration instructions
Authentication changes and best practices
Response format updates
Code examples for common integration patterns
Testing and validation procedures

In the meantime, you can explore the new V2 API Reference to familiarize yourself with the updated features and endpoints. For specific migration questions, please contact our support team at support@harbourshare.com.

This migration guide will be available soon to ensure a seamless upgrade experience for all our API users.

File Upload Guide

Overview

Uploading a file in Harbour's API is a two-step process:

Create a document with file metadata to get an upload URL
Upload the file content to the provided URL

Step-by-Step Process

1. Create Document with File Metadata

First, create a document including the file metadata to get an upload URL:

javascript

const documentData = {
  name: "My Document",
  files: [
    {
      name: "example.pdf",
      type: "application/pdf",
      size: 12345  // file size in bytes
    }
  ]
};

// Create document and get upload URL
const response = await fetch('https://api.myharbourshare.com/v2/documents', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify(documentData)
});

const data = await response.json();
const uploadUrl = data.files[0].upload_url;

2. Upload File Content

Once you have the upload URL, upload the file content:

javascript

await fetch(uploadUrl, {
  method: 'PUT',
  headers: {
    'Content-Type': file.type  // Must match the type provided in step 1
  },
  body: file  // The actual file content
});

Complete Example

Here's a complete example using axios:

javascript

async function uploadDocument(file) {
  try {
    // Step 1: Create document and get upload URL
    const documentData = {
      name: file.name.split('.').slice(0, -1).join('.'), // Use filename without extension
      file: {
        name: file.name,
        type: file.type,
        size: file.size
      }
    };

    const createResponse = await axios.post('/documents', documentData);
    const documentData = createResponse.data;
    
    // Step 2: Upload file content
    await axios.put(documentData.files[0].upload_url, file, {
      headers: { 'Content-Type': file.type }
    });

    return documentData;
  } catch (error) {
    console.error('Error uploading document:', error);
    throw error;
  }
}

Important Considerations

Upload URL Expiration
- The upload URL is temporary and expires quickly
- Upload the file content immediately after getting the URL
Content-Type Header
- The Content-Type header in the upload request must match the type provided when creating the document
- Mismatched content types will result in upload failures
Supported File Types
- PDF files (.pdf)
- Word documents (.docx)

Best Practices

Validation

javascript

function validateFile(file) {
  // Check file type
  const supportedTypes = ['application/pdf', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'];
  if (!supportedTypes.includes(file.type)) {
    throw new Error('Unsupported file type');
  }
}

Progress Tracking

javascript

async function uploadWithProgress(file, onProgress) {
  const documentData = await createDocument(file);
  
  await axios.put(documentData.files[0].upload_url, file, {
    headers: { 'Content-Type': file.type },
    onUploadProgress: (progressEvent) => {
      const percentCompleted = Math.round((progressEvent.loaded * 100) / progressEvent.total);
      onProgress(percentCompleted);
    }
  });
}

Retry Logic

javascript

async function uploadWithRetry(file, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await uploadDocument(file);
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
    }
  }
}

FAQs

Account & Authentication

Q: How do I get an API key? A: Sign up at Harbour Dashboard and generate a key in API Settings.

Q: Can I use the same API key for test and production? A: Yes, same API key will work for both test and production environments.

Document Management

Q: What file types are supported? A: We support PDF and DOCX files. Recommended file size is 50MB.

Q: How long are documents stored? A: Documents are stored indefinitely unless explicitly deleted. We maintain encrypted backups for 30 days.

Billing & Usage

Q: How is API usage billed? A: Usage is billed monthly based on:

Number of API requests
Document storage

Q: What are the rate limits? A: Standard accounts have 100 requests/minute. Contact sales for higher limits.

Technical Support

Q: How do I get help with integration? A: Contact support@harbourshare.com

Q: Where can I report security issues? A: Email security@harbourshare.com for security concerns.

Need more help? Contact our support team or check our API Reference.

Knowledge Base ​

Errors ​

Authentication Errors ​

Invalid API Key (2002) ​

Missing API Key (2001) ​

Validation Errors ​

Overview ​

Error Response Format ​

Error Response Fields ​

Validation Error Fields ​

Validation Error Types ​

Error Handling Best Practices ​

Guides ​

Migrating from V1 to V2 coming soon ​

File Upload Guide ​

Overview ​

Step-by-Step Process ​

1. Create Document with File Metadata ​

2. Upload File Content ​

Complete Example ​

Important Considerations ​

Best Practices ​

FAQs ​

Account & Authentication ​

Document Management ​

Billing & Usage ​

Technical Support ​

Knowledge Base

Errors

Authentication Errors

Invalid API Key (2002)

Missing API Key (2001)

Validation Errors

Overview

Error Response Format

Error Response Fields

Validation Error Fields

Validation Error Types

Error Handling Best Practices

Guides

Migrating from V1 to V2 coming soon

File Upload Guide

Overview

Step-by-Step Process

1. Create Document with File Metadata

2. Upload File Content

Complete Example

Important Considerations

Best Practices

FAQs

Account & Authentication

Document Management

Billing & Usage

Technical Support