Limits and Troubleshooting¶

flowchart TB
    R["Report request"] --> L{"Within your<br/>rate limits?"}
    L -->|no| RL["429 Rate Limit Exceeded"]
    L -->|yes| C{"Same licenses, path and<br/>data parameters in the<br/>last 5 minutes?"}
    C -->|yes| HIT["Served from cache,<br/>returns immediately"]
    C -->|no| B{"Under the row cap and<br/>small enough to build?"}
    B -->|no| X["Report Request Too Large,<br/>rejected before any data loads"]
    B -->|yes| G["Generating, usually 15 to 20 seconds"]
    G --> W{"Finished within<br/>240 seconds?"}
    W -->|yes| OK["Returned, and cached<br/>for the next 5 minutes"]
    W -->|no| T["504, but generation continues.<br/>Request it again and it<br/>usually comes from cache"]

Limits¶

Rate limits are counted per T3+ subscription, and every request counts, including one served from cache. Over a limit, the request returns 429. Emailed reports are also limited to 10 a minute, and point-in-time reports to 2 built an hour.

A report is refused before it loads when it would be too large to build. Each include adds work for every record, so a super report with one include tops out near 5,000 records, and fewer with more includes. See Report Request Too Large.

Caching and Timing¶

Caching. Identical report requests are served from a cache for 5 minutes. "Identical" means the same licenses, the same path, and the same parameters that select data (filter, filterLogic, sort, rowLimit, include and so on). Parameters that only shape the output do not count: change columns, contentType, columnHeaderOverrides, rowMode, transform, prependCsvMetadata or contentDisposition and the report is served from cache and returns immediately. See Shaping a Report.

Because license order determines row order, licenseNumber=A&licenseNumber=B and licenseNumber=B&licenseNumber=A are different reports and cache separately.

This matters for Spreadsheet Sync: IMPORTDATA refreshes roughly once an hour, which is well outside the cache window, so each refresh gets fresh data. But if you refresh manually several times in a row, or have several sheets pulling the same Sync Link, you will get the same document back until the five minutes elapse.

Timing. Reports usually finish in 15–20 seconds. A request waits up to 240 seconds before giving up.

If the wait elapses you get a 504 response, but the report keeps building, so it has not failed. Request it again; by then it has usually finished and comes straight from the cache.

A report has about five minutes to build. One that needs longer fails however you request it, so narrow it with filters or a rowLimit. delivery=email removes the 240-second wait: it returns a receipt immediately and sends the report when it is ready, or an email explaining why it failed.

Troubleshooting¶

Report Request Too Large¶

This one title covers two different limits, and the message tells you which you hit.

Too many rows:

Too many records to fetch: 120000. Please refine your filters so fewer than 50000 is returned.

Your collection is bigger than the report's row cap, 50,000 for a report, 5,000 for a super report. Reports reject an oversized collection rather than silently returning part of it, because a truncated spreadsheet looks exactly like a complete one.

Too large to build:

Report too large: 25000 records with 1 includes. Refine filters to reduce record count, reduce includes, or set a lower rowLimit.

The report would be too large to build. The message names what drove it up: the record count and the number of includes.

Any of these will bring either version back under the limit:

1. Filter harder. &filter=locationName__eq:Bulk Storage on a report that currently returns everything is usually the biggest win, and gives you a more useful report besides.
2. Add a row limit. &rowLimit=1000 caps the record count directly. Both limits are checked against the limited count, not the full collection, so this works on either version of the error.
3. Drop an include. Each one you remove takes work off every record.
4. Use the plain report. If you did not need the related data, the plain report takes no include and has a 50,000 row cap.

Transfer manifest reports hit this limit at a few thousand transfers even though they take no include, and their message names only the record count. See Transfer manifest reports work differently.

Too Many Includes for 2D Format¶

2D output formats (CSV) support a maximum of 1 include parameter. You requested 2 includes: labResults, history.
Use JSON for multiple includes, or specify only one include.

Switch to &contentType=json, or request one include and run a second report for the other. See One include in tabular formats, many in JSON.

Invalid Include¶

Unrecognized include `labresults`. This endpoint accepts: history, sourceHarvests,
labResultBatches, labResults, coaResults.

The include value is not one this report accepts. Include names are case-sensitive, and each report accepts a different set. The error lists the ones that work here.

Two common causes:

• A comma-joined list. &include=labResults,history is one value, not two. Repeat the parameter instead: &include=labResults&include=history.
• An include from a different report. plants works on a harvest super report but not on a package one; each report attaches only what its own records relate to.

Every endpoint's valid includes are published as an enum in the API documentation.

Invalid columns¶

The following columns are not valid for MetrcPackage: labResults.
Valid columns: id, label, packageType, quantity, ...

One of the names in your &columns= list is not a column on this report's data model. The error lists every valid name, so the fix is usually visible in the response itself.

Two common causes:

• A related object rather than a column. labResults is data you attach with include on a super report, not a column you select with columns.
• Nested syntax where it does not apply. Only packages support item.*, and only for four fields. See Specifying Field Names.

Report Generation Timeout¶

Report generation did not complete within the timeout period. Please try again.

A 504 after 240 seconds. The report is still being generated: request the same URL again and it will usually be ready and cached. If it happens repeatedly, the report is probably close to the limits. Narrow it with filters or a rowLimit, or switch to delivery=email, which returns at once instead of waiting. An emailed report must still finish building within about five minutes.

Next Steps¶

• Cut a too-large report down with Shaping a Report.
• Have a slow report sent to you instead by emailing it.
• Browse working requests in Report Examples.