Error handling

The Data API reports problems on two layers at once: the HTTP status code and a FileMaker error code inside the response body. Read both. The HTTP status tells you the transport-level category; the body code tells you what FileMaker actually objected to.

{
  "response": {},
  "messages": [
    { "code": "952", "message": "Invalid FileMaker Data API token (*)" }
  ]
}

Note that code is a string. Write your comparisons against "952", not 952.

Codes you actually encounter

FileMaker code	Typical HTTP status	Meaning	What to do
0	200	Success	Nothing. This is the happy path.
100	404	File is missing	Check the {database} path segment; the name is the hosted file name without .fmp12.
101	404	Record is missing	The recordId does not exist. Treat as a stale reference, not a retry case.
102	400 or 500	Field is missing	A field name in fieldData or a query does not exist on the layout. Field names are layout-scoped: the field must be placed on the layout you are calling.
105	404	Layout is missing	Check the {layout} path segment for typos and case.
212	401	Invalid account or password	Re-check credentials, then confirm the account is active and its privilege set has the fmrest extended privilege.
306	400	Record modification ID does not match	Someone changed the record after you read it. Re-read, reconcile, resubmit. See optimistic locking.
401	404	No records match the request	An empty find result. Usually not an error at all. See handling empty finds.
500	400	Date value does not meet validation	Field-level validation rejected the write. The message names the constraint type, not the field; check your payload against the schema.
504	400	Value in field is not unique	A unique-validation field rejected a duplicate. Surface this to the user rather than retrying.
952	401	Invalid Data API token	The token expired (15 minutes idle) or was already invalidated. Log in again and retry once.
953	400	Exceeded maximum data allowed	The response would be too large. Page with _limit and _offset instead of fetching everything.

The full error code list is in the Claris help center.

A sane retry policy

Most FileMaker errors are not retryable, because they are statements about your request, not about transient conditions. A reasonable default policy:

• 952 (invalid token): log in again, retry the original request once, then fail.
• HTTP 5xx with no parseable body: retry with backoff, two or three attempts. This is the server or the network, not FileMaker logic.
• Everything else: do not retry. Log the FileMaker code and message, fix the request or surface the condition.

Log what your future self needs

When you log a Data API failure, capture the HTTP status, the FileMaker code, the message, the method and path (without the token), and the recordId or query involved. The pair of status plus code is the diagnosis; either one alone is a guess.