Limits and Troubleshooting¶

Limits¶

The Metrc request budget is the one worth understanding. Generating a report costs T3 a number of requests to Metrc: some for paging through your data, plus (on a super report) one request per record for every include you asked for. If the estimate exceeds 10,000, the request is rejected before any data is loaded. See Report Request Too Large.

In practice this means a super report with one include tops out around 5,000 records, which is exactly where the row cap sits. Two includes will bind before the row cap does.

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 query parameters. 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; the report is still being generated in the background, so it has not failed. Simply request it again; by then it has usually finished and comes straight from the cache.

If a report exceeds 240 seconds every time, retrying will never help, it cannot be delivered over HTTP at all. Use delivery=email, which returns a receipt immediately and sends the report when it is ready, however long that takes.

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 many Metrc requests:

Estimated Metrc requests (25008) exceeds budget (10000). Record count: 25000, includes: 1.
Refine filters to reduce record count, reduce includes, or set a lower rowLimit.

Your report would cost more Metrc requests than the budget allows. The message tells you exactly what drove it up: the record count and the number of includes. Each include costs one request per record, so 25,000 packages with one include is 25,000 requests on its own.

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=5000 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. If you asked for two, each one you remove cuts the cost by one request per record.
4. Use the plain report. If you did not actually need the related data, the report form usually has no per-record cost and a much higher row cap.

Note that a filter on these reports selects transfers. Every package and transporter leg on a matched transfer is returned in full, so filtering does not reduce the per-transfer cost, it reduces how many transfers you pay it for.

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.

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 does not wait and so cannot time out.

Next Steps¶

• Cut a too-large report down with Shaping a Report.
• Move a slow report off the request path by emailing it.
• Browse working requests in Report Examples.