Error Reference

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

Error Response Format

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

{
  "error": "ErrorType",
  "message": "Human-readable error description",
  "details": {
    "field": "Additional context (when applicable)"
  }
}

HTTP Status Codes

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

Success Codes

Status Code	Description
`200 OK`	Request succeeded, response contains requested data
`201 Created`	Resource was successfully created
`204 No Content`	Request succeeded, no response body

Client Error Codes

Status Code	Description	Common Causes
`400 Bad Request`	Invalid request format or parameters	Missing required fields, invalid JSON, malformed data
`401 Unauthorized`	Authentication failed	Missing API key, invalid API key, expired token
`403 Forbidden`	Insufficient permissions	Valid API key but lacking workspace access or resource permissions
`404 Not Found`	Resource doesn't exist	Invalid workspace ID, knowledge ID, or category ID
`409 Conflict`	Resource conflict	Attempting to create a resource that already exists
`422 Unprocessable Entity`	Request valid but cannot be processed	Business logic validation failed

Server Error Codes

Status Code	Description	Action
`500 Internal Server Error`	Server encountered an error	Retry request, contact support if persists
`502 Bad Gateway`	Upstream service unavailable	Retry with exponential backoff
`503 Service Unavailable`	Service temporarily unavailable	Retry after delay indicated in Retry-After header

Common Errors

Authentication Errors

Missing Authorization Header

{
  "error": "Unauthorized",
  "message": "Missing Authorization header"
}

Solution: Include the Authorization: Bearer YOUR_API_KEY header in your request.

Invalid API Key

{
  "error": "Unauthorized",
  "message": "Invalid or expired API key"
}

Solution: Verify your API key is correct and hasn't been revoked. Generate a new API key if needed.

Workspace Access Denied

{
  "error": "Forbidden",
  "message": "Insufficient permissions for this workspace"
}

Solution: Ensure your API key has access to the specified workspace.

Validation Errors

Missing Required Fields

{
  "error": "Bad Request",
  "message": "Missing required field: type",
  "details": {
    "field": "type",
    "required": true
  }
}

Solution: Check the endpoint documentation and include all required fields in your request body.

Invalid Field Value

{
  "error": "Bad Request",
  "message": "Invalid value for field 'type'. Expected one of: FILE, URL, LINK, STRING",
  "details": {
    "field": "type",
    "provided": "INVALID",
    "expected": ["FILE", "URL", "LINK", "STRING"]
  }
}

Solution: Provide a valid value as specified in the endpoint documentation.

Invalid JSON

{
  "error": "Bad Request",
  "message": "Invalid JSON in request body"
}

Solution: Ensure your request body is valid JSON format.

Resource Errors

Resource Not Found

{
  "error": "Not Found",
  "message": "Knowledge item not found"
}

Solution: Verify the resource ID exists and you have permission to access it.

Search Query Error

{
  "error": "Bad Request",
  "message": "Either 'q' or 'title' parameter is required"
}

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

Processing Errors

Background Job Error

{
  "error": "Internal Server Error",
  "message": "Failed to queue background job",
  "details": {
    "jobType": "KNOWLEDGE_CREATION"
  }
}

Solution: Retry the request. If using async processing, try synchronous mode instead.

Rate Limiting

When you exceed rate limits, you'll receive a 429 Too Many Requests response:

{
  "error": "Rate Limit Exceeded",
  "message": "Too many requests. Please try again later.",
  "retryAfter": 60
}

The retryAfter field indicates seconds to wait before retrying.

Solution: Implement exponential backoff and respect the Retry-After header.

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 Error Details

Always log the full error response for debugging:

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

3. Handle Specific Status Codes

Different status codes require different handling strategies:

switch (response.status) {
  case 400:
    // Fix request parameters
    break;
  case 401:
    // Refresh or regenerate API key
    break;
  case 404:
    // Resource doesn't exist, handle gracefully
    break;
  case 429:
    // Implement backoff, respect rate limits
    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:

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