Errors · FFL Monkey Docs

The error envelope

Field	When	What it holds
error	always	A code such as `validation_failed`. Branch on this.
message	always	A sentence for a person.
errors	validation_failed	Each field, and what was wrong with it.
reason	license_not_active	`license_suspended`, `license_canceled` or `license_pending`.
required_scope	insufficient_scope	The scope the key needs.
required_product	product_not_included	The FFL Monkey product the endpoint is part of: `data_feed` or `ffl_checkout`.
acknowledge_field	zero_match_confirmation_required	The field to send as `true` with the same request to save anyway: `acknowledge_zero_match`.
wipe_shape	catalogue_wipe_confirmation_required	`exclude_everything`, an exclude with no condition, or `first_only_show`, the store's first only-show.
confirm_token	catalogue_wipe_confirmation_required	The token to send back as `confirm_token` with the same request to save anyway.

New codes may be added, so treat an unknown error by its HTTP status.

Every error answer, in this envelope or not, also carries the header X-FFL-Error-Reference, such as BE-7K3QX9PM. Log it with the error, and quote it when you write to us from Support in your FFL Monkey account or at [email protected]: it lets us find your request.

Every error code

Select a row to see its full response on the rightunder the table.

Status	`error`	What it means, and what to do
401	invalid_api_key	The key is missing, malformed, unknown or revoked.What to do: Check the header, or create a new key.
403	license_not_active	The store's subscription is not active. `reason` is `license_suspended`, `license_canceled` or `license_pending`. GET /key still answers in both APIs, and says the same in `license`, as does the Store API's GET /store. Its GET /subscription answers too, with a link to pay from.What to do: The key is fine: the subscription needs attention.
403	product_not_included	The endpoint is part of the other FFL Monkey product: a Data Feed key asked for FFL dealers or FFL orders, or an FFL Checkout key for in-house inventory, products, pricing rules, restrictions or distributors. `required_product` names the product it needs.What to do: Use a key made for a licence of that product, in your FFL Monkey account.
403	insufficient_scope	The key lacks the permission the endpoint needs: a key with In-house inventory: Read tried to change something, or a key without Products and changes asked for products. `required_scope` names what it needs.What to do: Create a key with that permission in your FFL Monkey account.
404	dealer_not_found	Store API only. No dealer in the registry has that licence number, in any form, or only an upload still pending or rejected.What to do: Check the number, or find the dealer with GET /dealers/search.
404	ffl_order_not_found	Store API only. The store has no FFL order with that order number: it was never reported, or it is another store's.What to do: Report it with POST /ffl-orders, using the same order number.
404	ffl_contribution_not_found	Store API only. The store has no licence upload with that id: it was never made, or it is another store's.What to do: Use the id POST /ffl-contributions answered with.
404	item_not_found	Inventory API only. The store has no row for that UPC.What to do: Create it with PUT or the batch endpoint first.
404	product_not_found	Store API only. The store has no price for that product id, so it is not in the store's catalog.What to do: Use an id from GET /products or from a change.
404	pricing_rule_not_found	Store API only. The store has no pricing rule with that id: there never was one, it was deleted, or it is another store's.What to do: Use an id from GET /pricing-rules.
404	restriction_not_found	Store API only. The store has no restriction with that id: there never was one, it was deleted, or it is another store's.What to do: Use an id from GET /restrictions.
404	distributor_not_found	Store API only. No distributor has that slug, or, to connect one, FFL Monkey no longer offers it.What to do: Use a slug from GET /distributors.
404	webhook_not_set	Store API only. The store has no webhook to read, test or remove.What to do: Set one with PUT /webhook.
404	not_found	No such address under `/inventory`, `/products`, `/pricing-rules`, `/restrictions`, `/distributors`, `/dealers`, `/ffl-orders` or `/ffl-contributions`: a product id that is not a number, say. Any other address under the base URL that is no endpoint answers `404` with a bare `{"message": ""}` instead, without this envelope.What to do: Check the path against the endpoint list.
405	method_not_allowed	That path does not take that HTTP method.What to do: Check the method against the endpoint list.
409	idempotency_key_reused	The `Idempotency-Key` was already used for a different adjustment.What to do: Use a new key for each new adjustment.
409	sync_paused	Store API only. The store has switched catalog sync off in its FFL Monkey screens, so its products are not served. It is not an empty catalog.What to do: Keep what you have and retry later. Once it answers again, read your products again.
409	webhook_managed_by_plugin	Store API only. The store's FFL Monkey Data Feed plugin is connected and manages its webhook, which already receives every change, so the API does not change, test or remove it.What to do: Nothing: the plugin gets every change. A store has one webhook URL.
410	cursor_expired	Store API only. The cursor sent to GET /changes is older than the changes kept, at least 30 days.What to do: Read GET /products again and carry on from its `meta.changes_cursor`.
413	payload_too_large	The body is too big.What to do: Send fewer items per batch.
422	validation_failed	The request broke a rule. `errors` lists each field and what was wrong.What to do: Fix the fields named in `errors`.
422	zero_match_confirmation_required	Store API only. The pricing rule or restriction would match no product in the catalog, so it was not saved. `acknowledge_field` names the field that saves it anyway.What to do: If you meant it (the stock is still to arrive, say), send the same request again with `"acknowledge_zero_match": true`. Otherwise check its conditions.
422	catalogue_wipe_confirmation_required	Store API only. The restriction would hide every product in your store (`wipe_shape` `exclude_everything`), or is your first only-show and would hide everything it does not match (`first_only_show`), so it was not saved.What to do: If you meant it, send the same request again with `confirm_token` set to the `confirm_token` in the answer.
422	credentials_rejected	Store API only. The distributor did not accept the credentials sent to PUT /distributors/{slug}, so nothing was saved. Credentials saved before are kept.What to do: Check them with the distributor, then try again. Do not retry the same ones: a distributor may lock an account after repeated failed sign-ins.
429	rate_limited	Too many requests for this key: more than 120 a minute. Four Store API calls have a limit of their own per store: 5 webhook tests a minute, 10 previews of pricing rules and restrictions together, 5 distributor connects a minute and 20 an hour, and 6 FFL licence uploads a minute. Dealer searches share your checkout's limits: 120 a minute from one address, and 5,000 a day for the store.What to do: Wait for `Retry-After` seconds. Use batch for many rows.
4xx	bad_request	Any other problem with the request.What to do: Check the request against these docs.
500	server_error	Something went wrong on our side.What to do: Retry; if it keeps happening, write to us from Support in your FFL Monkey account, or at [email protected].
502	distributor_unreachable	Store API only. The distributor did not answer when FFL Monkey checked the credentials sent to PUT /distributors/{slug}: a timeout, a refused connection or an error on its side. Nothing was saved.What to do: The credentials may be right: try again in a few minutes.

Retrying safely

429: wait the number of seconds in Retry-After, then send the same request again. To write many rows, use POST /items/batch: it counts as one request.
500: retry; if it keeps happening, write to us from Support in your FFL Monkey account, or at [email protected].
Adjustments: retry with the same Idempotency-Key, so a retry can never take away a unit twice. See Idempotency.
PUT, PATCH and batch set absolute values, so sending one twice is harmless.