Lokalise Common Errors

Overview

Every Lokalise API error returns a JSON body with a consistent structure. This skill covers the error response format, diagnosis of each HTTP status code (401, 400, 404, 429, 413, 500, 503), diagnostic curl commands for rapid troubleshooting, and a reusable error handling wrapper for the Node SDK.

Prerequisites

• curl

  available for diagnostic commands

• @lokalise/node-api

  SDK installed for the error wrapper
• API token stored in

  LOKALISE_API_TOKEN

  environment variable

• jq

  installed for parsing JSON responses (optional but recommended)

Instructions

1. Understand the Error Response Format

All Lokalise API errors return this structure:

{
  "error": {
    "message": "Human-readable error description",
    "code": 401
  }
}

The

code

message

error.code

error.message

error.headers

2. Diagnose by Status Code

401 Unauthorized — Invalid or Missing API Token

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

Causes:

• Token is incorrect, expired, or revoked

• X-Api-Token

  header missing from request
• Token copied with leading/trailing whitespace

Fix:

# Verify your token works
curl -s -o /dev/null -w "%{http_code}" \
  -H "X-Api-Token: ${LOKALISE_API_TOKEN}" \
  "https://api.lokalise.com/api2/teams"

# Expected: 200
# If 401: regenerate token at https://app.lokalise.com/profile#apitokens

# Check for whitespace in token
echo -n "$LOKALISE_API_TOKEN" | xxd | head -2
# Look for 0a (newline) or 20 (space) at start/end

400 Bad Request — Validation Errors

{"error": {"message": "Invalid parameter `platform` - must be one of: ios, android, web, other", "code": 400}}

Common 400 causes:

• Invalid

  project_id

  format (must be

  {number}.{alphanumeric}

  )
• Missing required fields in POST/PUT body
• Invalid language ISO code
• Key name exceeding 256 characters
• Invalid platform value (must be

  ios

  ,

  android

  ,

  web

  , or

  other

  )

Fix:

# Validate project ID format
curl -s -H "X-Api-Token: ${LOKALISE_API_TOKEN}" \
  "https://api.lokalise.com/api2/projects/${PROJECT_ID}" | jq '.project_id'

# List valid languages for a project
curl -s -H "X-Api-Token: ${LOKALISE_API_TOKEN}" \
  "https://api.lokalise.com/api2/projects/${PROJECT_ID}/languages" \
  | jq '.languages[].lang_iso'

404 Not Found — Resource Does Not Exist

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

Causes:

• Project ID is wrong or project was deleted
• Key, translation, or webhook ID does not exist
• Token lacks access to the specified project (appears as 404, not 403)

Fix:

# List all accessible projects to find the correct ID
curl -s -H "X-Api-Token: ${LOKALISE_API_TOKEN}" \
  "https://api.lokalise.com/api2/projects?limit=100" \
  | jq '.projects[] | {project_id, name}'

# Verify a specific key exists
curl -s -H "X-Api-Token: ${LOKALISE_API_TOKEN}" \
  "https://api.lokalise.com/api2/projects/${PROJECT_ID}/keys/${KEY_ID}" \
  | jq '.key_id // .error'

429 Too Many Requests — Rate Limited

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

The response includes a

Retry-After

Fix: See

lokalise-rate-limits

# Check current rate limit status on any request
curl -s -D - -o /dev/null \
  -H "X-Api-Token: ${LOKALISE_API_TOKEN}" \
  "https://api.lokalise.com/api2/projects" 2>&1 \
  | grep -i "x-ratelimit\|retry-after"

# Output:
# X-RateLimit-Limit: 6
# X-RateLimit-Remaining: 5
# X-RateLimit-Reset: 1700000001

413 Payload Too Large — Request Body Exceeds Limit

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

Causes:

• File upload exceeds 50 MB
• Bulk key creation with too many keys in one request (max 500)
• Translation value exceeds character limit

Fix:

• Split bulk operations into batches of 500 items
• Compress files before upload or split into smaller files
• For large translation values, check if the content truly belongs in a translation key

500 Internal Server Error / 503 Service Unavailable

{"error": {"message": "Internal server error", "code": 500}}

These are Lokalise-side issues. Do not retry immediately in a tight loop.

Fix:

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

# If status is operational, retry after 30 seconds
# If status shows incident, wait for resolution

Retry strategy for 500/503: wait 30 seconds, retry up to 3 times, then alert.

3. Run Diagnostic Commands

Quick health check script to diagnose the most common issues in sequence:

#!/bin/bash
# lokalise-diagnose.sh — Run against your environment
TOKEN="${LOKALISE_API_TOKEN}"
PROJECT="${LOKALISE_PROJECT_ID}"

echo "=== 1. Token validation ==="
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "X-Api-Token: $TOKEN" \
  "https://api.lokalise.com/api2/teams")
if [ "$STATUS" = "200" ]; then
  echo "Token: VALID"
else
  echo "Token: INVALID (HTTP $STATUS)"
  exit 1
fi

echo "=== 2. Project access ==="
curl -s -H "X-Api-Token: $TOKEN" \
  "https://api.lokalise.com/api2/projects/$PROJECT" \
  | jq '{project_id: .project_id, name: .name, team_id: .team_id}'

echo "=== 3. Rate limit status ==="
curl -s -D /dev/stderr -o /dev/null \
  -H "X-Api-Token: $TOKEN" \
  "https://api.lokalise.com/api2/projects" 2>&1 \
  | grep -i "x-ratelimit"

echo "=== 4. Key count ==="
curl -s -H "X-Api-Token: $TOKEN" \
  "https://api.lokalise.com/api2/projects/$PROJECT/keys?limit=1" \
  | jq '.project_id as $p | {project: $p, total_keys: .keys | length}'

4. Build a Reusable Error Handling Wrapper

Wrap all SDK calls with structured error handling:

import { LokaliseApi } from "@lokalise/node-api";

interface LokaliseError {
  code: number;
  message: string;
  headers?: Record<string, string>;
}

function isLokaliseError(error: unknown): error is LokaliseError {
  return (
    typeof error === "object" &&
    error !== null &&
    "code" in error &&
    "message" in error
  );
}

async function lokaliseCall<T>(
  fn: () => Promise<T>,
  context: string
): Promise<T> {
  try {
    return await fn();
  } catch (error) {
    if (!isLokaliseError(error)) throw error;

    switch (error.code) {
      case 401:
        throw new Error(
          `[${context}] Authentication failed. ` +
          `Regenerate token at https://app.lokalise.com/profile#apitokens`
        );
      case 400:
        throw new Error(
          `[${context}] Invalid request: ${error.message}. ` +
          `Check parameter values and required fields.`
        );
      case 404:
        throw new Error(
          `[${context}] Resource not found: ${error.message}. ` +
          `Verify the project/key/resource ID exists and token has access.`
        );
      case 429:
        console.warn(`[${context}] Rate limited. See lokalise-rate-limits.`);
        throw error; // Let the rate limit handler deal with retries
      case 413:
        throw new Error(
          `[${context}] Payload too large: ${error.message}. ` +
          `Split into smaller batches (max 500 items per request).`
        );
      case 500:
      case 503:
        throw new Error(
          `[${context}] Lokalise server error (${error.code}). ` +
          `Check https://status.lokalise.com — retry after 30s.`
        );
      default:
        throw new Error(
          `[${context}] Lokalise error ${error.code}: ${error.message}`
        );
    }
  }
}

// Usage
const lokalise = new LokaliseApi({ apiKey: process.env.LOKALISE_API_TOKEN! });

const keys = await lokaliseCall(
  () => lokalise.keys().list({ project_id: projectId, limit: 500 }),
  "listKeys"
);

Output

• Identified error cause and specific fix for the HTTP status code encountered
• Diagnostic curl commands validated against live API
• Reusable error wrapper providing actionable messages per error type

Error Handling

Retry-After

Examples

Quick Token Check (One-Liner)

curl -s -H "X-Api-Token: $LOKALISE_API_TOKEN" \
  "https://api.lokalise.com/api2/teams" | jq '.teams[0].name // "INVALID TOKEN"'

SDK Error Inspection

try {
  await lokalise.keys().list({ project_id: "invalid" });
} catch (e: any) {
  console.log("Code:", e.code);       // 400
  console.log("Message:", e.message); // "Invalid project ID format"
  console.log("Headers:", e.headers); // rate limit headers
}

CLI Diagnostics

# Verify CLI token
lokalise2 project list --token "$LOKALISE_API_TOKEN" --format json | jq '.[0].name'

# Test with verbose output
lokalise2 --debug file download \
  --token "$LOKALISE_API_TOKEN" \
  --project-id "$PROJECT_ID" \
  --format json \
  --dest ./locales/

Resources

• Lokalise API Error Codes
• Lokalise Status Page
• Lokalise Community Forum
• @lokalise/node-api Error Handling

Next Steps

For building resilient integrations that handle errors automatically, see

lokalise-rate-limits

lokalise-data-handling