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".
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)
The code field mirrors the HTTP status code. The field provides specifics. When using the Node SDK, errors are thrown as exceptions with , , and properties.
# 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 header indicating seconds to wait.
Fix: See lokalise-rate-limits skill for full implementation. Quick recovery:
# 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:
For building resilient integrations that handle errors automatically, see lokalise-rate-limits. For debugging translation data issues, see lokalise-data-handling.
