Error Reference

This page documents error responses, status codes, and troubleshooting guidance for the Sharely.ai API.

Error Response Format

Error responses from the Sharely.ai API follow a consistent JSON structure:

{
  "error": "Human-readable error description",
  "errorId": "550e8400-e29b-41d4-a716-446655440000"
}

HTTP Status Codes

The Sharely.ai API uses standard HTTP status codes to indicate success or failure of requests.

Success Codes

Client Error Codes

Server Error Codes

Common Errors

Authentication Errors

Missing Authorization Header

{
  "error": "Missing Authorization header",
  "errorId": "..."
}

Solution: Include the Authorization: Bearer {access_token} header in your request. The access token is obtained by calling the /workspaces/{workspaceId}/generate-access-key-token endpoint with your API key in the x-api-key header. See Authentication for the complete flow.

Invalid Access Token

{
  "error": "Invalid or expired API key",
  "errorId": "..."
}

Solution: The access token may be expired or invalid. Generate a new access token by calling /workspaces/{workspaceId}/generate-access-key-token with your API key in the x-api-key header. If you're passing the raw API key directly as a Bearer token, this will not work — you must use the two-step authentication flow.

Workspace Mismatch

{
  "error": "Token does not match workspace",
  "errorId": "..."
}

Solution: Access tokens are bound to a workspace. Ensure the workspaceId in the URL matches the workspace the token was generated for.

Validation Errors

Validation failures return 400 with a message describing the first failing field:

{
  "error": "type must be one of the following values: FILE, URL, LINK, STRING",
  "errorId": "..."
}

Solution: Check the endpoint documentation and correct the offending field. Validation messages name the field and the expected format.

Resource Errors

Resource Not Found

{
  "error": "Knowledge not found",
  "errorId": "..."
}

Solution: Verify the resource ID exists and belongs to the workspace in the URL. Soft-deleted resources also return 404.

Search Query Error

{
  "error": "Either 'q' or 'title' parameter is required",
  "errorId": "..."
}

Solution: Provide at least one search parameter as required by the endpoint.

Best Practices for Error Handling

1. Implement Retry Logic

For transient errors (500, 502, 503), implement retry logic with exponential backoff:

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.ok) return response;
 
      // Retry on server errors
      if (response.status >= 500 && i < maxRetries - 1) {
        await new Promise(resolve =>
          setTimeout(resolve, Math.pow(2, i) * 1000)
        );
        continue;
      }
 
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

2. Log the errorId

Always log the full error response — the errorId is the key to server-side diagnosis:

if (!response.ok) {
  const errorData = await response.json();
  console.error('API Error:', {
    status: response.status,
    error: errorData.error,
    errorId: errorData.errorId
  });
}

3. Handle Specific Status Codes

Different status codes require different handling strategies:

switch (response.status) {
  case 400:
    // Fix request parameters
    break;
  case 401:
    // Regenerate the access token from your API key
    break;
  case 403:
    // The operation crosses a permission boundary — don't retry
    break;
  case 404:
    // Resource doesn't exist, handle gracefully
    break;
  case 500:
  case 502:
  case 503:
    // Retry with backoff
    break;
}

4. Validate Before Sending

Validate request data before sending to reduce 400 errors:

function validateKnowledgeCreation(data) {
  const validTypes = ['FILE', 'URL', 'LINK', 'STRING'];
 
  if (!data.type) {
    throw new Error('type is required');
  }
 
  if (!validTypes.includes(data.type)) {
    throw new Error(`type must be one of: ${validTypes.join(', ')}`);
  }
 
  // Additional validation...
}

Getting Help

If you encounter persistent errors or need assistance:

1. Check this documentation for solutions
2. Review your API key and permissions
3. Verify request format matches endpoint specifications
4. Contact support at support@sharely.ai with:
   • Request details (endpoint, method, parameters)
   • Full error response including the errorId
   • Timestamp of the error
   • Your workspace ID (if applicable)

See Also

• Authentication - Authentication setup and troubleshooting
• API Overview - General API information
• Knowledge API - Knowledge endpoint reference