Errors

Explore the comprehensive error reference for the Lia API - HTTP status codes, error codes, and best practices for error handling.

Error Response Format

All error responses follow this structure:

{
  "code": "ERROR_CODE",
  "message": "Human-readable error message",
  "status": 400
}

Fields:

• code: Machine-readable error code for programmatic handling

• message: Human-readable description of the error

• status: HTTP status code

HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:

Code	Description	Common Causes
200	OK	Request succeeded
400	Bad Request	Invalid parameters, validation errors
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error (contact support)
503	Service Unavailable	Temporary downtime or maintenance

Error Codes

BAD_REQUEST

Invalid input parameters or validation errors.

Example:

{
  "code": "BAD_REQUEST",
  "message": "Invalid target language code: 'xyz'",
  "status": 400
}

Common causes:

• Invalid parameter values

• Missing required fields

• Malformed JSON in request body

• Invalid pagination parameters

Solution: Check the error message for details and verify your request parameters.

UNAUTHORIZED

Missing or invalid API key.

Example:

{
  "code": "UNAUTHORIZED",
  "message": "Missing API key. Include x-api-key header in your request.",
  "status": 401
}

Common causes:

• Missing x-api-key header

• Invalid or expired API key

• Revoked API key

Solution: Include a valid API key in the x-api-key header.

Authentication

FORBIDDEN

API key is valid but lacks permissions to access the resource.

Example:

{
  "code": "FORBIDDEN",
  "message": "Insufficient permissions to access this resource",
  "status": 403
}

Common causes:

• Workspace doesn't have access to the requested feature

• Resource belongs to a different workspace

• Feature requires a higher plan

Solution: Verify your workspace has access to the feature. Contact support if needed.

NOT_FOUND

The requested resource doesn't exist.

Example:

{
  "code": "NOT_FOUND",
  "message": "Context with id 'ctx_123' not found",
  "status": 404
}

Common causes:

• Resource ID is incorrect

• Resource has been deleted

• Resource belongs to a different workspace

Solution: Verify the resource ID is correct and the resource exists.

TOO_MANY_REQUESTS

Too many requests in a given time period. Rate limited to 120 requests per 60 seconds per API key.

Example:

{
  "code": "TOO_MANY_REQUESTS",
  "message": "Rate limit exceeded. Please try again later.",
  "status": 429
}

Response Headers:

• X-RateLimit-Limit: Maximum requests per window

• X-RateLimit-Remaining: Remaining requests

• X-RateLimit-Reset: Unix timestamp when limit resets

• Retry-After: Seconds to wait before retrying

Solution: Implement exponential backoff and respect rate limit headers. See the rate limiting guide for best practices.

https://github.com/acoladgroup/lia/blob/main/docs/product/developers/lia-api/rate-limiting.md

INTERNAL_ERROR

An unexpected error occurred on the server.

Example:

{
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred. Please try again.",
  "status": 500
}

Solution: Retry the request. If the error persists, check the status page for ongoing incidents or contact support with the request ID from the X-Request-Id response header.

SERVICE_UNAVAILABLE

The API is temporarily unavailable.

Example:

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Service temporarily unavailable. Please try again later.",
  "status": 503
}

Response Headers:

• Retry-After: Seconds to wait before retrying

Solution: Retry the request after the specified delay. Check the status page for ongoing incidents.

Example Error Responses

Validation Error

curl -X POST https://api.acolad.ai/translate/text \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "", "targetLang": "fr"}'

Response:

{
  "code": "BAD_REQUEST",
  "message": "Text cannot be empty",
  "status": 400
}

Authentication Error

curl https://api.acolad.ai/whoami

Response:

{
  "code": "UNAUTHORIZED",
  "message": "Missing API key. Include x-api-key header in your request.",
  "status": 401
}

Not Found Error

curl https://api.acolad.ai/translate/contexts/ctx_invalid \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "code": "NOT_FOUND",
  "message": "Context with id 'ctx_invalid' not found",
  "status": 404
}

Error Handling Best Practices

Check HTTP Status Codes

Always check the HTTP status code before processing the response:

const response = await fetch('https://api.acolad.ai/translate/text', {
  method: 'POST',
  headers: {
    'x-api-key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ text: 'Hello', targetLang: 'fr' })
});

if (!response.ok) {
  const error = await response.json();
  console.error(`Error ${error.status}: ${error.message}`);
  throw new Error(error.message);
}

const data = await response.json();

Handle Specific Error Codes

Handle different error types appropriately:

try {
  const result = await translateText('Hello', 'fr');
} catch (error) {
  switch (error.code) {
    case 'UNAUTHORIZED':
      // Refresh API key or show login prompt
      break;
    case 'TOO_MANY_REQUESTS':
      // Implement exponential backoff
      await sleep(error.retryAfter * 1000);
      break;
    case 'NOT_FOUND':
      // Handle missing resource
      break;
    default:
      // Generic error handling
      console.error('API error:', error.message);
  }
}

Implement Retry Logic

Implement exponential backoff for retryable errors (rate limits, server errors):

async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);

      if (response.ok) {
        return response;
      }

      // Don't retry client errors (4xx) except rate limits
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        throw new Error('Client error');
      }

      // Exponential backoff: 1s, 2s, 4s
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

Rate Limiting

When rate limited (429 status), respect the retry timing:

async function handleRateLimit(response: Response) {
  const retryAfter = response.headers.get('Retry-After');
  const resetTime = response.headers.get('X-RateLimit-Reset');

  if (retryAfter) {
    // Wait the specified seconds
    await new Promise(resolve => setTimeout(resolve, parseInt(retryAfter) * 1000));
  } else if (resetTime) {
    // Wait until reset time
    const waitMs = parseInt(resetTime) * 1000 - Date.now();
    await new Promise(resolve => setTimeout(resolve, Math.max(0, waitMs)));
  }
}