Lokalise Common Errors

Lokalise Common Errors

Overview

Quick reference for the most common Lokalise API errors and their solutions.

Prerequisites

• Lokalise SDK/CLI installed
• API token configured
• Access to error logs

Instructions

Step 1: Identify the Error

Check error message, HTTP status code, and error code in logs or console.

Step 2: Find Matching Error Below

Match your error to one of the documented cases.

Step 3: Apply Solution

Follow the solution steps for your specific error.

Error Handling

401 Unauthorized - Invalid API Token

Error Message:

{
  "error": {
    "code": 401,
    "message": "Invalid `X-Api-Token` header"
  }
}

Cause: API token is missing, expired, revoked, or incorrect.

Solution:

# Verify token is set
echo $LOKALISE_API_TOKEN | head -c 10

# Test token validity
curl -X GET "https://api.lokalise.com/api2/projects" \
  -H "X-Api-Token: $LOKALISE_API_TOKEN"

# Generate new token if needed:
# Profile Settings -> API tokens -> Generate new token

403 Forbidden - Insufficient Permissions

Error Message:

{
  "error": {
    "code": 403,
    "message": "Forbidden"
  }
}

Cause: Token lacks required permissions for the operation.

Solution:

• Verify token has read-write access (not read-only)
• Check project permissions in Team settings
• Ensure you're a contributor with appropriate role

// Check your permissions
const user = await lokaliseApi.teamUsers().list({ team_id: teamId });
console.log("User roles:", user.items.map(u => u.role));

404 Not Found - Resource Missing

Error Message:

{
  "error": {
    "code": 404,
    "message": "Project not found"
  }
}

Cause: Project ID, key ID, or other resource doesn't exist.

Solution:

# List available projects
lokalise2 --token "$LOKALISE_API_TOKEN" project list

# Verify project ID format (should include hash)
# Correct: 123456789.abcdef12
# Wrong: 123456789

// Get correct project ID
const projects = await lokaliseApi.projects().list();
projects.items.forEach(p => {
  console.log(`${p.name}: ${p.project_id}`);
});

429 Too Many Requests - Rate Limited

Error Message:

{
  "error": {
    "code": 429,
    "message": "Too many requests"
  }
}

Cause: Exceeded 6 requests/second or 10 concurrent requests per project.

Solution:

// Implement rate limiting
import PQueue from "p-queue";

const queue = new PQueue({
  concurrency: 5,
  interval: 1000,
  intervalCap: 5,
});

// Queue all requests
const result = await queue.add(() => lokaliseApi.keys().list({...}));

See lokalise-rate-limits for comprehensive handling.

400 Bad Request - Invalid Parameters

Error Message:

{
  "error": {
    "code": 400,
    "message": "Invalid request"
  }
}

Cause: Missing required fields or invalid parameter values.

Solution:

// Check required fields for key creation
const keys = await lokaliseApi.keys().create({
  project_id: projectId,  // Required
  keys: [{
    key_name: "my.key",   // Required
    platforms: ["web"],   // Required: web, ios, android, other
    // translations is optional
  }],
});

400 Key Limit Exceeded

Error Message:

{
  "error": {
    "code": 400,
    "message": "Keys limit exceeded"
  }
}

Cause: Exceeded maximum keys per request (500 as of 2025).

Solution:

// Batch keys in chunks of 500
async function createKeysInBatches(projectId: string, allKeys: any[]) {
  const batchSize = 500;
  const results = [];

  for (let i = 0; i < allKeys.length; i += batchSize) {
    const batch = allKeys.slice(i, i + batchSize);
    const result = await lokaliseApi.keys().create({
      project_id: projectId,
      keys: batch,
    });
    results.push(...result.items);

    // Respect rate limits
    await new Promise(r => setTimeout(r, 200));
  }

  return results;
}

413 Payload Too Large

Error Message:

{
  "error": {
    "code": 413,
    "message": "Request entity too large"
  }
}

Cause: File upload exceeds size limit.

Solution:

• Split large files into smaller chunks
• Compress file before upload
• Use async upload with polling

# Check file size
ls -lh locales/en.json

# Split by namespace if needed
# Split monolithic file into:
# - common.json
# - features.json
# - errors.json

Upload Process Failed

Error Message:

{
  "status": "failed",
  "details": "..."
}

Cause: File format issues, invalid characters, or parsing errors.

Solution:

# Validate JSON
cat locales/en.json | jq . > /dev/null

# Check for BOM or encoding issues
file locales/en.json
# Should show: UTF-8 Unicode text

# Remove BOM if present
sed -i '1s/^\xEF\xBB\xBF//' locales/en.json

Quick Diagnostic Commands

# Check Lokalise API status
curl -s https://status.lokalise.com/api/v2/status.json | jq '.status.description'

# Test API connectivity
curl -I -X GET "https://api.lokalise.com/api2/system/health"

# Verify token and list projects
curl -X GET "https://api.lokalise.com/api2/projects" \
  -H "X-Api-Token: $LOKALISE_API_TOKEN" | jq '.projects[].name'

# Check rate limit headers
curl -v -X GET "https://api.lokalise.com/api2/projects" \
  -H "X-Api-Token: $LOKALISE_API_TOKEN" 2>&1 | grep -i "x-ratelimit"

Escalation Path

1. Collect evidence with lokalise-debug-bundle
2. Check Lokalise Status Page
3. Search Lokalise Community
4. Contact support via support@lokalise.com

Resources

• API Error Codes
• Lokalise Status
• Community Forum

Next Steps

For comprehensive debugging, see lokalise-debug-bundle.