Facebook test API: "An unknown error has occurred" when creating new test user

When creating a test user via the Facebook graph API - with a POST to the /{app-id}/accounts/test-users edge - you can pass a "name" parameter in the POST body. Sometimes when you do this, you might get back an OAuth error with the message "An unknown error has occurred".

There are several possible causes for this, but here is one I have not seen documented anywhere else. It turns out the Facebook API is very sensitive to the format of the name you pass in. In particular, the name string must:

• Consist of exactly two words (a first and last name), separated by one space
• Both words must start with exactly one capital letter, with all subsequent letters lowercase
• Neither word may contain any numeric digits

Failing to have a name that adheres to these causes the "unknown error". There are probably other strictures as well. If you are creating a test user with a custom name, and encounter this error, try the API call with a safe name like "Joe Smith" and see whether it reproduces.

(This information is known to apply in 2014, to the Graph API v. 2.0; and may apply to earlier or later versions as well.)