FDA Recall API: A Working Guide to openFDA Enforcement

The openFDA enforcement API is free, keyless, and well documented on the surface. It is also full of failure modes that return HTTP 200 with quietly wrong data. Every number and error string below was measured against the live API on 2026-07-20; anything I could not reproduce has been cut. Pick the right endpoint first There are four recall-shaped endpoints and they are not interchangeable. Choosing wrong gives you a different universe of records with no warning. Endpoint Records What it is drug/enforcement.json 17,793 Recall Enterprise System (RES) drug recalls device/enforcement.json 39,519 RES device recalls food/enforcement.json 29,224 RES food recalls device/recall.json 58,756 CDRH device recall database, a different schema entirely The three enforcement endpoints share their schema. device/recall.json does not: its fields include cfres_id , product_res_number , k_numbers , root_cause_description , event_date_posted , event_date_terminated and recall_status , and it has no classification field at all ( count=classification.exact returns HTTP 404 "Nothing to count" ). If you are filtering for Class I, you want an enforcement endpoint. The two families also refresh on different clocks. On 2026-07-20 the three enforcement endpoints reported meta.last_updated of 2026-07-08, while device/recall.json reported 2026-07-17. The OR bug that silently returns the wrong answer This is the single most expensive trap, and it is undocumented. An unparenthesized OR discards every clause except the last one. All figures below are from food/enforcement.json . search=classification:"Class I" OR state:"CA" returns 4,003 - exactly the count for state:"CA" alone. Reverse the operands and you get 12,809 - exactly classification:"Class I" alone. Wrap it: search=(classification:"Class+I"+OR+state:"CA") returns 14,822 in both orders. That is the real union (12,809 + 4,003 - 1,990 overlap, and the AND of the two clauses does return 1,990). No error is raised in any case. The nastier varia