Troubleshooting

Find the symptom below, then the most likely cause and fix. Every v2 error carries a stable error code; see the error table for the full list.

Authentication

Symptom	Cause	Fix
401 MISSING_API_KEY	The x-apikey header was not sent.	Send the header on every request. Check that your HTTP client or proxy does not strip custom headers.
403 INVALID_API_KEY	The key is wrong, disabled, or could not be verified.	Copy the key again from your account. If it is correct, retry after a short wait.
403 FORBIDDEN on the reputation export	Your account lacks the reputation_export capability.	See plans and features.

A report or resource returns 404

A report you cannot see returns 404 NOT_FOUND, exactly like one that does not exist. Check, in order:

1. The ID. Report IDs are UUIDs. A malformed ID returns 400, not 404.
2. Visibility. Restricted and private reports are visible only to some accounts. See report visibility.
3. Review requests. A report under review is hidden from everyone.
4. Retention. Reports expire. See data retention.

For resource content, the hash must belong to a resource captured in that report, and the content must still be stored. A resource whose resource_available is false in the report cannot be downloaded.

Lists and search return less than expected

Symptom	Cause	Fix
A page has fewer than limit items, or none, but has_more is true	Visibility is checked after a page is selected.	Keep following next_cursor until has_more is false.
scope=team is always empty	Your account is not in a team.	Use scope=user for your own reports.
scope=all misses reports you can open	It lists your own reports and those open to your plan, not your team's restricted or private reports.	Use scope=team for team reports.
Related lists miss restricted reports	Related lists by domain and ASN return public reports only.	Search instead, for example url.domain:example.com.
Search finds nothing older than a year	Search covers only the last year; a date range narrows it but cannot extend it.	Open older reports directly by ID.
Search returns fewer items than limit	Results are filtered by visibility after matching; total_hits counts matches before filtering.	Page by adding limit to offset.
A content search for a common phrase misses reports	Content search matches a bounded number of captured documents.	Combine the phrase with structured fields such as url.domain or tags.

See the search syntax for field names and operators.

Submissions

Symptom	Cause	Fix
400 url must be an absolute http or https URL	The URL has no scheme, another scheme, or no host.	Send the full URL, including https://.
400 domain does not resolve	The host has no DNS answer.	Check the spelling. A newly registered domain can take a while to resolve.
400 url resolves to a non-public address	At least one address of the host is private, loopback, link-local, or otherwise not on the public internet.	Only public sites can be analyzed.
400 the URL cannot be submitted	The analysis service refused the URL, for example a blocked domain.	Search for existing reports instead.
400 about tags, meta, or an unknown field	A field is outside its limits, or is not part of the v2 request.	See the Submission API for each field. priority, exit_node, and referer are not accepted.
404 on GET /submissions/{queue_id}	The submission belongs to another account, or the ID is wrong.	Only you and your team can follow a submission. Use the queue_id from your own POST.
status is failed	The analysis did not produce a report.	Submit again later.
A submit timed out or returned 502/504	The analysis may already be queued.	Do not resubmit straight away; search for your tag or list scope=user reports first.

YARA rules

Symptom	Cause	Fix
422 YARA source does not compile	The source has a syntax error, uses an unknown module, or defines no rule.	Fix the lines named in message, or call POST /detection/yara/validate to see every error and warning. Includes are not allowed.
403 FORBIDDEN on a rule set	Only the set's owner can change or delete it.	Ask the owner.
403 FORBIDDEN on a rule	Teammates can change a rule only when it is shared with the team and can_team_edit is set.	Ask the owner to enable can_team_edit.
404 on a set or rule you know exists	It is private to another account, or no longer shared with your team.	Only the owner and, for shared sets and rules, their team can see them.
503 COMPILER_BUSY	Too many sources are compiling at once.	Retry after a few seconds.
400 new rules are always enabled	The create request had "enabled": false.	Create the rule, then replace it with "enabled": false.
404 report not found on POST /detection/yara/test	The report doesn't exist, or your key can't read it.	Use a report you can open with the same key.
A test finds no match where you expect one	The content wasn't scanned: check skipped. Response bodies that aren't stored (such as images) and files inside archives are not tested.	Test against content counted in scanned, or submit the page again after saving the rule. See When a test surprises you.
A rule no longer matches anything	It is disabled: enabled is false. You, a teammate who can edit it, or urlquery may have switched it off.	Replace it with "enabled": true, after checking why it was disabled.

See the YARA Detection API for the fields and a CI sync recipe.

Host Profile pivots

Symptom	Cause	Fix
400 exactly one of domain, ip, … is required	GET /hosts was sent with no pivot, or with two.	Send one fact parameter, for example ?certificate=<SHA256>.
400 include_apex is only valid with domain	A pivot-specific filter was sent with another pivot.	Use include_apex only with domain, and the cookie filters only with cookie.
400 mime must be a type/subtype media type	The MIME value has no subtype.	Send it as type/subtype, for example mime=text/html.
A host named search or relations cannot be profiled	Those names are reserved under /hosts.	Pivot on it instead, for example ?domain= or ?ip=.
A pivot returns hosts you did not expect	Common values (shared hosting IPs, popular technologies, generic header names) match many unrelated hosts.	Prefer distinctive facts such as certificate hashes and cookie attribute combinations. See Host Profile.

Pagination errors

Symptom	Cause	Fix
400 BAD_REQUEST about the cursor	The cursor was reused with a different scope or value, was modified, or is longer than 1024 characters.	Send next_cursor unchanged with the same parameters, or drop cursor to start over.
400 BAD_REQUEST about offset	offset plus limit is above 10000.	Narrow the query with a date range and page each range separately. See the workflows.

Rate limiting

Symptom	Cause	Fix
429 RATE_LIMIT_EXCEEDED	A route quota or your overall v2 quota is exhausted.	Wait Retry-After seconds. Read RateLimit-Remaining to slow down before you reach the limit.
429 on the reputation export while no other request is running	The limit on concurrent exports is reached, possibly by another member of your team.	Wait Retry-After seconds.
503 RATE_LIMIT_UNAVAILABLE	Quota enforcement is temporarily unavailable.	Retry with backoff. These requests are not counted.

Members of a team share one quota, so a teammate's automation can exhaust it for you.

Upstream failures

502 BAD_GATEWAY and 504 GATEWAY_TIMEOUT mean a urlquery service failed or timed out. Retry with exponential backoff. Very broad searches are the most common cause of timeouts; narrow the query or the date range.

Still stuck

Contact support with the request path, the time of the request, the full error envelope, and the report ID if there is one. Never send your API key.