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 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
{"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:
curl -s -o /dev/null -w "%{http_code}" \
-H "X-Api-Token: ${LOKALISE_API_TOKEN}" \
"https://api.lokalise.com/api2/teams"
echo -n "$LOKALISE_API_TOKEN" | xxd | head -2
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:
curl -s -H "X-Api-Token: ${LOKALISE_API_TOKEN}" \
"https://api.lokalise.com/api2/projects/${PROJECT_ID}" | jq '.project_id'
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:
curl -s -H "X-Api-Token: ${LOKALISE_API_TOKEN}" \
"https://api.lokalise.com/api2/projects?limit=100" \
| jq '.projects[] | {project_id, name}'
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 header indicating seconds to wait.
Fix: See lokalise-rate-limits skill for full implementation. Quick recovery:
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"
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:
curl -s "https://status.lokalise.com/api/v2/status.json" | jq '.status'
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
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. ` +
);
:
(
+
);
:
(
+
);
:
.();
error;
:
(
+
);
:
:
(
+
);
:
(
);
}
}
}
lokalise = ({ : process..! });
keys = (
lokalise.().({ : projectId, : }),
);
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
| Code | Error | Root Cause | Resolution |
|---|
| 401 | Invalid API Token | Token wrong, expired, or whitespace | Regenerate at Lokalise profile |
| 400 | Bad Request | Invalid params, missing fields | Check API docs for required fields |
| 404 | Not Found | Wrong ID or no access | List resources to find correct ID |
| 429 | Rate Limited | Exceeded 6 req/sec | Honor Retry-After, use queue |
| 413 | Payload Too Large | Body > 50 MB or > 500 items | Split into batches |
| 500 | Internal Server Error | Lokalise-side failure | Check status page, retry after 30s |
| 503 | Service Unavailable | Lokalise maintenance/outage | Check status page, wait |
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);
console.log("Message:", e.message);
console.log("Headers:", e.headers);
}
CLI Diagnostics
lokalise2 project list --token "$LOKALISE_API_TOKEN" --format json | jq '.[0].name'
lokalise2 --debug file download \
--token "$LOKALISE_API_TOKEN" \
--project-id "$PROJECT_ID" \
--format json \
--dest ./locales/
Resources
Next Steps
For building resilient integrations that handle errors automatically, see lokalise-rate-limits. For debugging translation data issues, see lokalise-data-handling.
