Every error is JSON with a stable error code for programs and a message for people:
{ "error": "invalid_nsn", "message": "Expected a 13-character NSN such as 5305-00-123-4567, or a 9-character NIIN." }
Write code against error and the HTTP status. The message wording can change.
| Status | error |
Meaning | What to do |
|---|---|---|---|
| 400 | invalid_nsn, invalid_cage, invalid_fsc, invalid_inc |
The identifier is not in the right format | Fix the value |
| 400 | invalid_include |
Unknown section name in include |
Use the names in Endpoints |
| 400 | missing_q, missing_partnumber, too_long |
A required parameter is missing, shorter than 2 characters, or too long | Fix the request |
| 400 | invalid_paging |
page below 1, pageSize outside 1 to 25, or paging past the first 100 results |
Narrow the search |
| 400 | batch_too_large, no_nsns |
A batch has more NSNs than your plan allows, or none | Split the batch |
| 401 | unauthorized |
No key, wrong key, or disabled key | Check the header and the key |
| 403 | plan_upgrade_required |
Your plan does not include this endpoint or tool | See the plans below |
| 404 | not_found |
Nothing has that NSN, CAGE, FSC or INC | Normal outcome, not a fault |
| 429 | rate_limited |
Your key sent too many requests this minute | Wait Retry-After seconds |
| 429 | daily_limit |
Your key (or IP, without a key) has had its plan's number of different NSNs today | NSNs already returned today still work; new ones after 00:00 UTC |
| 429 | daily_search_limit |
Your key has used its plan's searches for today (/v19/search, /v19/parts, MCP search tools) |
Look-ups still work; searches again after 00:00 UTC |
| 429 | enumeration_detected |
Requests walk the catalog (sequential NIINs, or one FSC in order) | Paused for 15 minutes. The API is for the NSNs you need, not for copying the database |
| 429 | quota_exceeded |
Your key has used all of its requests for this calendar month (UTC) | Upgrade the plan on your account page, or wait until resetsAt |
| 503 | unavailable |
The data service is briefly unavailable | Retry after Retry-After seconds |
| 500 | server_error |
Unexpected fault on our side | Retry later; report it if it continues |
429 with a Retry-After header. Nothing is queued.Retry 429 and 503 after the Retry-After delay, and 500 with a growing delay (1 s, 2 s, 4 s). Do not retry 400, 401 or 404: the answer will not change.
FLIS catalog data is refreshed on a monthly cycle. A record you fetched yesterday is very likely still current, so cache results on your side for repeated lookups.
Every response to a key that has a monthly limit carries three headers, so a program can slow down before it is cut off.
| Header | Meaning |
|---|---|
X-Quota-Limit |
Requests your plan allows in a calendar month |
X-Quota-Remaining |
Requests left this month, after this one |
X-Quota-Reset |
When the count returns to zero: the first of next month, 00:00 UTC |
REST calls and MCP calls count the same. A call refused with rate_limited or unauthorized is not counted.
| Plan | Requests / minute | Requests / month | Different NSNs looked up / day | Searches / day | Batch | Includes |
|---|---|---|---|---|---|---|
| Anonymous (no key, per IP) | 10 | - | 50 | 50 | 1 | /v19/export only |
| Free | 10 | 1,000 | 50 | 200 | 5 | NSN, search, parts, CAGE, FSC, INC, export |
| Developer | 60 | 50,000 | 2,500 | 2,000 | 25 | Free + weight-dims, trade-codes, repairable, photos |
| Business | 300 | 500,000 | 25,000 | 20,000 | 100 | Developer + stock, price, lead time, RFQ (coming soon) |
| Enterprise | 600 | 5,000,000 | 250,000 | 200,000 | 250 | As Business, custom terms |
The daily NSN limit counts different NSNs returned by look-ups (/v19/nsn, the section endpoints and batches); looking up an NSN you already had today is free. Search results do not count against it: searches have their own daily allowance, 25 results per page and the first 100 results per search. Plans and prices: https://www.nsnlookup.com/nsn-api/pricing.