Lokalise Common ErrorsSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: lokalise-common-errors
description: 'Diagnose and fix Lokalise common errors and exceptions.

  Use when encountering Lokalise errors, debugging failed requests,

  or troubleshooting integration issues.

  Trigger with phrases like "lokalise error", "fix lokalise",

  "lokalise not working", "debug lokalise", "lokalise 401", "lokalise 429".

  '
allowed-tools: Read, Grep, Bash(curl:*), Bash(lokalise2:*)
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- lokalise
- debugging
compatibility: Designed for Claude Code
---
# 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:

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

The `code` field mirrors the HTTP status code. The `message` field provides specifics. When using the Node SDK, errors are thrown as exceptions with `error.code`, `error.message`, and `error.headers` properties.

### 2. Diagnose by Status Code

#### 401 Unauthorized — Invalid or Missing API Token

```json
{"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:**

```bash
# 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
```

```bash
# 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

```json
{"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:**

```bash
# 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

```json
{"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:**

```bash
# 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

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

The response includes a `Retry-After` header indicating seconds to wait.

**Fix:** See `lokalise-rate-limits` skill for full implementation. Quick recovery:

```bash
# 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

```json
{"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

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

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

**Fix:**

```bash
# 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:

```bash
#!/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" \
  "ht

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.