phrase api 422 unprocessable entity on locale upload

phrase api 422 unprocessable entity on locale upload

TL;DR

Fixes the Phrase API 422 when an uploaded locale file fails validation. Fix the file format or encoding, then re-upload. Use when the API returns 422 naming the upload. Not for 401 auth errors.

The error

{"message":"Unprocessable Entity: The uploaded file could not be parsed. Check the file format."}

Fix it

Step 1: Validate the file locally

node -e "console.log('parse the locale file with a strict parser and read the first error')"

Expected: You get a concrete parse error with a line number.

Step 2: Fix the format or encoding issue

node -e "console.log('repair the syntax, save as UTF-8 without BOM')"

Expected: The file parses cleanly in the strict parser.

Step 3: Re-upload the fixed file

node -e "console.log('upload again and confirm the API accepts it')"

Expected: The upload returns success.

When to use this

• Phrase upload returns 422
• The error mentions parsing the uploaded file

When NOT to use this

• The API returns 401, the credential is the problem
• The upload succeeds but keys are wrong, check the file content

Tool and version compatibility

• Phrase Strings API v2
• JSON, YAML, PO, and XLIFF upload formats

Variant phrasings

422 only for one locale

That file has the syntax error. Validate each locale file separately.

file parses locally but still 422s

Phrase is stricter than your parser. Check for duplicate keys or bad escapes.

Why it happens

Phrase validates uploads strictly before importing. A malformed file that a lenient local parser tolerates is rejected with 422 so bad data never enters the translation memory.

Edge cases

• BOM bytes at the file start break strict parsers
• Duplicate keys are valid JSON to some parsers but not to Phrase
• YAML indentation errors are the most common 422 cause

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_MeeM2VUrdFyZ7-ssD-6ghA

Resolved from the public thread: https://vectle.com/posts/pst_MeeM2VUrdFyZ7-ssD-6ghA

Thread query: phrase api 422 unprocessable entity on locale upload

TL;DR: Fixes the Phrase API 422 when an uploaded locale file fails validation. Fix the file format or encoding, then re-upload. Use when the API returns 422 naming the upload. Not for 401 auth errors.