Skip to main content

Troubleshooting

This guide covers common issues with Spectra Intelligence APIs and feeds and the steps to resolve them.

401 Unauthorized response​

Symptom

Every API request returns:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Spectra Intelligence"

Cause

  • The Authorization header is missing from the request.
  • The credentials in the Authorization header are incorrect.
  • The credential string is not correctly base64-encoded for HTTP Basic authentication.
  • The account has been suspended or deactivated.

Solution

  1. Confirm that every request includes the Authorization header using HTTP Basic authentication. All Spectra Intelligence APIs require this header, as described in Sending requests.
curl -u "<username>:<password>" \
  "https://data.reversinglabs.com/api/databrowser/malware_presence/query/sha1/<hash>?format=json"
  1. Verify your credentials by logging in to the ReversingLabs portal. If your password has changed recently, regenerate or update it in all scripts and integrations.
  2. If using the ReversingLabs Python SDK, check that the username and password parameters passed to the client constructor are correct:
from ReversingLabs.SDK.ticloud import FileReputation
client = FileReputation(
    host="https://data.reversinglabs.com",
    username="<username>",
    password="<password>"
)
  1. If credentials are correct but requests still return 401, contact support@reversinglabs.com to verify that your account is active.

403 Forbidden response​

Symptom

API requests return:

HTTP/1.1 403 Forbidden

The response body may not include a descriptive message.

Cause

  • Your account does not have a subscription or entitlement for the specific API endpoint you are calling.
  • You are attempting to access a service that requires an upgrade to your current contract.

Solution

  1. Review the API reference page for the endpoint you are calling. Each service documents the required entitlement tier.
  2. Check which APIs are included in your contract by contacting support@reversinglabs.com or your ReversingLabs account manager.
  3. If you believe your account should have access, confirm that you are using the correct username (including the company segment, for example u/company/username) — accessing APIs with an account from a different company segment may result in 403 responses.

404 Not Found — hash not in database​

Symptom

A hash lookup returns:

HTTP/1.1 404 Not Found

Cause

  • The queried hash has not yet been seen by the ReversingLabs database.
  • The hash value is malformed or contains an encoding error.
  • You are querying a hash type (for example, MD5) for an endpoint that expects a different hash type (for example, SHA-1).

Solution

  1. A 404 response for a hash query is not an error — it means the file has not been seen by Spectra Intelligence. This is a normal response for previously unseen files. According to the response status codes, 404 means no matching record was found.
  2. Verify that the hash string is correctly formatted and uses the expected algorithm. For example, SHA-1 is 40 hex characters:
# Compute SHA-1 of a local file to cross-check
sha1sum /path/to/file
  1. If you are certain the file has been analyzed before, check whether you are querying the correct API endpoint. Some endpoints accept only specific hash types; see the relevant API reference (for example, File Threat Intelligence).

429 Too Many Requests — quota exceeded​

Symptom

API requests return:

HTTP/1.1 429 Too Many Requests

You may also receive an automated alert email from ReversingLabs.

Cause

  • Your account's daily or monthly quota has been exhausted.
  • Your request rate has exceeded the per-second rate limit for the API, which returns an additional "Rate limit exceeded" message.

Solution

  1. Check whether this is a quota exhaustion or a rate limit issue. A rate-limit response includes an additional message:
{"message": "Rate limit exceeded"}

Quota exhaustion responses typically do not include a body beyond the 429 status.

  1. For rate limiting: implement exponential backoff and retry logic in your client. Spread bulk lookups across time rather than submitting all requests simultaneously.
  2. For quota exhaustion: daily quotas reset at 00:00 UTC and monthly quotas reset on the first of the month at 00:00 UTC, as described in Limits and quotas.
  3. Monitor your quota consumption proactively using the Customer Usage API before reaching the limit.
  4. If your quota is regularly insufficient for your use case, contact your ReversingLabs account manager to discuss an upgrade.
  5. For bulk operations, prefer the bulk query endpoints where available. Bulk queries count only successful items against your quota, as explained in Limits and quotas.

Request timeout on large queries​

Symptom

Large bulk requests or queries with many items fail with a client-side timeout or return:

HTTP/1.1 503 Service Unavailable

after an extended wait.

Cause

  • The client HTTP timeout is shorter than the time required to process a large bulk request.
  • A network intermediary (proxy, load balancer) is enforcing a shorter timeout than the API requires.
  • The request contains close to or more than the maximum allowed number of items (100 hashes per bulk request).

Solution

  1. Check the response status codes table. A 503 indicates a temporary overload on the server side; retry the request after a short delay.
  2. Ensure your bulk requests do not exceed 100 items. Requests exceeding this limit return HTTP 413. Split large datasets into batches of 100 or fewer:
def batch(items, size=100):
    for i in range(0, len(items), size):
        yield items[i:i + size]

for chunk in batch(all_hashes):
    response = client.get_bulk_results(chunk)
  1. Increase the HTTP client timeout in your code. For the Python SDK, pass a timeout parameter:
response = client.file_reputation(hash_input=sha1, timeout=60)
  1. If timeouts are caused by a proxy, configure the proxy to allow longer-lived connections to data.reversinglabs.com.

SSL/TLS certificate error​

Symptom

Requests to the Spectra Intelligence API fail with an error such as:

curl: (60) SSL certificate problem: unable to get local issuer certificate

or in Python:

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed

Cause

  • The system's CA certificate bundle does not include the root CA that signed the ReversingLabs server certificate.
  • A network security appliance (TLS inspection proxy) is presenting its own certificate instead of the ReversingLabs certificate, and it is not trusted by the client.
  • The system clock is significantly wrong, causing certificate validity checks to fail.

Solution

  1. Verify the server certificate from the command line:
curl -vI https://data.reversinglabs.com 2>&1 | grep -E "subject|issuer|expire"
  1. Update the CA certificate bundle on your system:
# Debian/Ubuntu
sudo apt-get update && sudo apt-get install --reinstall ca-certificates

# RHEL/CentOS
sudo yum reinstall ca-certificates
  1. If a TLS inspection proxy is in use, add the proxy's root CA certificate to your system trust store or pass it explicitly:
curl --cacert /path/to/proxy-ca.pem \
  -u "<username>:<password>" \
  "https://data.reversinglabs.com/..."
  1. Verify that the system clock is accurate:
date
timedatectl status

Significant clock skew causes certificate validation to fail even with a valid certificate.

  1. Do not use --insecure (-k in curl) or verify=False in Python in production environments, as this disables certificate validation entirely and exposes your traffic to interception.

Python SDK connection error​

Symptom

Using the ReversingLabs Python SDK, requests raise exceptions such as:

requests.exceptions.ConnectionError: HTTPSConnectionPool(host='data.reversinglabs.com', port=443): Max retries exceeded

or:

requests.exceptions.ConnectTimeout

Cause

  • The machine running the SDK cannot reach data.reversinglabs.com over HTTPS (port 443).
  • A proxy is required but not configured in the SDK or the environment.
  • DNS resolution for data.reversinglabs.com is failing.

Solution

  1. Test basic connectivity from the machine:
curl -I https://data.reversinglabs.com

If this fails, the issue is network-level, not SDK-related.

  1. Check DNS resolution:
nslookup data.reversinglabs.com
dig data.reversinglabs.com
  1. If a proxy is required, configure it via environment variables before running the SDK:
export HTTPS_PROXY="http://proxy.company.internal:8080"

Or pass proxy settings directly to the SDK client using the underlying requests.Session:

import requests
from ReversingLabs.SDK.ticloud import FileReputation

session = requests.Session()
session.proxies = {"https": "http://proxy.company.internal:8080"}

client = FileReputation(
    host="https://data.reversinglabs.com",
    username="<username>",
    password="<password>",
    proxies={"https": "http://proxy.company.internal:8080"}
)
  1. Verify that the SDK version is up to date: pip install --upgrade reversinglabs-sdk-py3.

Batch request returns partial results​

Symptom

A bulk API request containing multiple hashes returns fewer results than the number of items submitted. Some hashes are missing from the response.

Cause

  • Hashes that are not found in the database (404) are omitted from bulk response bodies rather than returned as error entries — only valid, found results are included.
  • Some items in the request were invalid (malformed hashes) and were silently skipped.
  • The request contained more than 100 items, causing it to be rejected (HTTP 413) or truncated.

Solution

  1. Cross-reference the hashes in your request against the hashes in the response. Any hash absent from the response was either not found (not yet seen by Spectra Intelligence) or was invalid.
  2. Validate hash formats before submission. SHA-1 hashes must be exactly 40 lowercase hex characters. Malformed entries are skipped and not counted against quota.
  3. Note that the quota deduction model for bulk requests counts only valid returned results — invalid items are not charged. Confirming this behavior can help you detect malformed input.
  4. Keep batch sizes at or below 100 items to avoid HTTP 413 responses.

TAXII feed returns no data​

Symptom

Polling the TAXII feed returns an empty collection or no STIX objects, even though new threat intelligence is expected.

Cause

  • The added_after timestamp used in the collection request is set to a future time, or is more recent than the latest available data.
  • The TAXII client is not sending the correct collection ID.
  • The account does not have entitlement for the TAXII feed.
  • The collection has not yet published new data within the polled time window.

Solution

  1. Check the added_after parameter in your TAXII request. Set it to a known past timestamp to verify that objects are returned:
# Example: request objects from the past 24 hours
added_after=$(date -u -d '24 hours ago' +"%Y-%m-%dT%H:%M:%SZ")
  1. Confirm you are using the correct TAXII collection ID. Refer to the TAXII feed documentation for available collection IDs and their content.
  2. Verify your TAXII client is authenticating correctly with Basic auth credentials.
  3. Test the feed endpoint directly with curl to isolate whether the issue is with the client or the server:
curl -u "<username>:<password>" \
  "https://data.reversinglabs.com/api/taxii/flexible-intel-feeds/collections/<collection-id>/objects/?added_after=2024-01-01T00:00:00Z"
  1. If you receive a 403 response, confirm with your account manager that the TAXII feed is included in your contract.

Unexpected UNKNOWN classification​

Symptom

A hash lookup or file analysis returns a classification of UNKNOWN rather than malicious, suspicious, or goodware.

Cause

  • The file has not been seen by the ReversingLabs network before, so no classification exists yet.
  • The file is a novel or rare variant that has not been analyzed by enough sources to produce a confident verdict.
  • The hash is for a container file whose classification depends on extracted children, and those children have not been analyzed.

Solution

  1. An UNKNOWN result is not an error — it means the file has no established reputation in the Spectra Intelligence database. This is expected for newly discovered or very rare files.
  2. To obtain a classification for an unknown file, submit it for analysis on a Spectra Analyze appliance. Spectra Analyze uses Spectra Core to perform deep static analysis and can produce a local classification.
  3. Review the classification methodology to understand how classifications are assigned and what factors contribute to a confident verdict.
  4. If you are seeing a high volume of UNKNOWN results for files that you believe are malicious, they may be custom or targeted malware. Submit samples through your ReversingLabs support channel for analyst review.