API error responses - OpenSourceMalware Docs

This page covers all eight API endpoints:

the six read endpoints: check-malicious, query-latest, threat-feed, false-positive, threat-data, query-by-username
the two write endpoints:submit-threat-report, modify-threat-report

A CORS OPTIONS preflight request returns 204 or 200 — this is expected browser behavior, not an error.

Quick reference

	Status	Meaning
`400`	Bad request — missing or invalid parameters	All endpoints
`401`	Missing, invalid, or inactive credentials	All endpoints
`403`	Account tier or role doesn’t meet the requirement	threat-feed, threat-data, false-positive, query-by-username, submit-threat-report
`404`	Resource not found	threat-data, modify-threat-report
`405`	Method not allowed	All endpoints
`409`	Conflict — duplicate record	submit-threat-report
`429`	Rate limit or quota exceeded	All endpoints
`500`	Internal server error	All endpoints

Shared errors — read endpoints

These are returned by every read endpoint (check-malicious, query-latest, threat-feed, false-positive, threat-data, query-by-username). Wording and status are identical unless noted per endpoint below.

405 — Method not allowed

{ "error": "Method not allowed" }

query-by-username variant: "Method not allowed. Use GET."

429 — IP rate limit (500 req / 15 min per IP)

{ "error": "Rate limit exceeded for your IP address. Please try again later." }

429 — Token rate limit (per-minute, tier-scoped)

{ "error": "Rate limit exceeded. Maximum 60 requests per minute (standard tier)." }

429 — Daily quota exceeded

{
  "error": "Daily quota exceeded: 2000/2000 requests in the last 24 hours (free tier). Upgrade to Pro for higher limits.",
  "upgrade_url": "https://opensourcemalware.com/pro-features",
  "tier": "free",
  "used": 2000,
  "limit": 2000
}

threat-feed and query-by-username omit the trailing "Upgrade to Pro for higher limits." sentence but keep the same fields.

500 — Internal server error

{ "error": "Internal server error" }

check-malicious

401 — Missing API token

{ "error": "API token required. Provide token in Authorization header or apikey query parameter." }

401 — Invalid or inactive token

{ "error": "Invalid or inactive API token" }

400 — Invalid or missing `report_type`

{ "error": "Invalid or missing 'report_type' parameter. Valid types: <comma-separated list of VALID_TYPES>" }

400 — Missing `resource_identifier`

{ "error": "Missing required 'resource_identifier' parameter." }

400 — Invalid repository format

{ "error": "Invalid repository format. Must include protocol (e.g., 'https://github.com/org/repo' or 'http://gitlab.example.com/org/repo')." }

500 — Database query failed

{ "error": "Database query failed" }

query-latest

401 — Missing API token

{ "error": "API token required. Provide it via Authorization header (Bearer token) or apikey query parameter." }

401 — Invalid token

{ "error": "Invalid API token" }

401 — Inactive token

{ "error": "API token is inactive" }

400 — Missing `ecosystem`

{ "error": "ecosystem parameter is required" }

500 — Query failed

{ "error": "Failed to query threats" }

threat-feed

401 — Missing API token

{ "error": "API token required. Provide it via Authorization header (Bearer token) or apikey query parameter." }

401 — Invalid token

{ "error": "Invalid API token" }

401 — Inactive token

{ "error": "API token is inactive" }

403 — Endpoint requires Core/Pro/Enterprise

{ "error": "This endpoint requires a Core, Pro, or Enterprise role. Contact an administrator to request access." }

403 — `unverified=true` requires Pro/Enterprise

{
  "error": "The 'unverified' parameter requires a Pro or Enterprise role.",
  "upgrade_url": "https://opensourcemalware.com/pro-features"
}

400 — Invalid `hours`

{ "error": "hours parameter must be an integer between 1 and 24" }

400 — Missing `ecosystem`

{ "error": "ecosystem parameter is required" }

500 — Query failed

{ "error": "Failed to query threats" }

threat-data

401 — Missing API token

{ "error": "API token required. Provide token in Authorization header or apikey query parameter." }

401 — Invalid or inactive token

{ "error": "Invalid or inactive API token" }

403 — Requires Pro/Editor/Admin

{ "error": "Access denied. This endpoint requires Pro, Editor, or Admin access." }

400 — Missing `threat_id`

{ "error": "Missing required parameter: threat_id" }

400 — Invalid UUID

{ "error": "Invalid threat_id format. Must be a valid UUID." }

404 — Not found or not verified/modified

{ "error": "Threat not found or not in verified/modified status." }

false-positive

400 — Missing ecosystem parameter

{ "error": "ecosystem parameter is required" }

400 — Invalid hours parameter

{ "error": "hours parameter must be an integer between 1 and 24" }

400 — Invalid source parameter

{ "error": "source parameter must be 'threat' or 'osv_withdrawal'" }

401 — Missing API token

{ "error": "API token required. Provide token in Authorization header or apikey query parameter." }

401 — Invalid or inactive token

{ "error": "Invalid or inactive API token" }

403 — Insufficient role (e.g. standard tier)

{
  "error": "This endpoint requires a Core, Pro, or Enterprise role. Contact an administrator to request access.",
  "upgrade_url": "https://opensourcemalware.com/pro-features"
}

405 — Wrong HTTP method (only GET is allowed)

{ "error": "Method not allowed" }

429 — IP rate limit (500 requests per 15 minutes per IP)

{ "error": "Rate limit exceeded for your IP address. Please try again later." }

429 — Token rate limit (per minute; varies by tier)

{ "error": "Rate limit exceeded. Maximum 60 requests per minute (standard tier)." }

The number and tier name change with the caller’s role: 60 for standard/trial, 180 for pro/enterprise, 360 for admin/editor.

429 — Daily quota exceeded

{
  "error": "Daily quota exceeded: 2001/2000 requests today (free tier). Upgrade to Pro for higher limits.",
  "upgrade_url": "https://opensourcemalware.com/pro-features",
  "tier": "free",
  "used": 2001,
  "limit": 2000
}

tier/used/limit reflect the caller’s actual tier — trial counts as free (2,000/day), pro/core 25,000, enterprise 50,000, admin/editor unlimited.

500 — Threats query failed

{ "error": "Failed to query false positives" }

500 — OSV withdrawals query failed

{ "error": "Failed to query OSV withdrawals" }

500 — Unexpected error (catch-all)

{ "error": "Internal server error" }

query-by-username

401 — Missing API token

{ "error": "Missing API token. Provide via Authorization header or apikey query parameter." }

401 — Invalid token

{ "error": "Invalid API token" }

401 — Inactive token

{ "error": "API token is inactive" }

403 — Requires Pro/Enterprise

{"error":"This endpoint requires a Core, Pro, or Enterprise role. Contact an administrator to request access."}

400 — Missing params

{
  "error": "Missing required parameters. Both ecosystem and username are required.",
  "example": "/query-by-username?ecosystem=npm&username=malicious-publisher"
}

500 — Failed to verify permissions

{ "error": "Failed to verify permissions" }

500 — Database query failed

{ "error": "Database query failed" }

Write endpoints

submit-threat-report and modify-threat-report rate limits are per-hour (submission/modification counts) rather than per-minute.

submit-threat-report

401 — No Authorization header

{ "error": "Authorization required" }

401 — Invalid API token (`osm_...`)

{ "error": "Invalid API token" }

429 — IP rate limit

{ "error": "Rate limit exceeded for your IP address. Please try again later." }

429 — Submission rate limit (per hour)

{ "error": "Rate limit exceeded. Maximum 10 submissions per hour." }

10/hour for Free users. Limit may be increased by an admin.

403 — New-user unverified cap

{
  "error": "New users are limited to 3 unverified reports. You currently have 3 unverified reports. Once 3 of your reports are verified, this limit will be removed.",
  "verified_reports": 0,
  "unverified_reports": 3
}

405 — Method not allowed

{ "error": "Method not allowed" }

400 — Missing required fields

{ "error": "Missing required fields: report_type, resource_identifier, and threat_description are required" }

409 — Duplicate package in registry

Returned only for package reports, when a report with the same package_name and registry already exists in any status, including pending, rejected, and false positive. Matching is exact and case-sensitive. Other report types aren’t checked for duplicates. To update the existing report, pass existingThreatId to modify-threat-report as threat_id.

{
  "error": "A threat report for this package in this registry already exists. Please use the \"Update Report\" functionality to modify the existing report.",
  "existingThreatId": "<uuid>",
  "packageName": "<package-name>",
  "registry": "npm",
  "status": "verified"
}

500 — Existing-package lookup failed

{
  "error": "Failed to check for existing package",
  "details": "<postgres error message>"
}

500 — Threat insert failed

Also returned when a field has a value the database doesn’t accept, such as an unsupported report_type or severity_level.

{
  "error": "Failed to create threat report",
  "details": "<postgres error message>"
}

500 — Threat details insert failed (threat was rolled back)

{
  "error": "Failed to create threat details",
  "details": "<postgres error message>"
}

500 — Catch-all

{
  "error": "Internal server error",
  "details": "<exception message>"
}

modify-threat-report

401 — No Authorization header

{ "error": "Authorization required" }

401 — Invalid API token

{ "error": "Invalid API token" }

429 — IP rate limit (whitelisted IPs bypass)

{ "error": "Rate limit exceeded for your IP address. Please try again later." }

429 — Modification rate limit (per hour)

{ "error": "Rate limit exceeded. Maximum 30 modifications per hour." }

30/hour for standard users. This limit may be increased by an admin.

405 — Method not allowed

{ "error": "Method not allowed" }

400 — No target identifier supplied

{ "error": "Missing required field: either threat_id, package_name, or resource_identifier is required" }

404 — Lookup by `package_name` returned nothing

{ "error": "No threat report found for this package name" }

404 — Lookup by `resource_identifier` returned nothing

{ "error": "No threat report found for this resource_identifier" }

404 — `threat_id` not found

{ "error": "Threat report not found" }

500 — Lookup by package_name failed

Also returned when more than one report matches the package_name, for example the same name in two registries with no registry value sent. Use threat_id instead.

{
  "error": "Failed to lookup threat by package name",
  "details": "<postgres error message>"
}

500 — Lookup by resource_identifier failed

Also returned when more than one report matches the resource_identifier. Use threat_id instead.

{
  "error": "Failed to lookup threat by resource_identifier",
  "details": "<postgres error message>"
}

500 — Fetch existing threat failed

{
  "error": "Failed to fetch threat report",
  "details": "<postgres error message>"
}

500 — Version-creation prefetch failed (pro-user edit path)

{ "error": "Failed to fetch threat for version creation" }

500 — Save proposed changes failed (pro-user edit path)

{
  "error": "Failed to save proposed changes",
  "details": "<postgres error message>"
}

500 — Admin/editor threat update failed

Also returned when a field has a value the database doesn’t accept, such as an unsupported severity_level.

{
  "error": "Failed to update threat report",
  "details": "<postgres error message>"
}

500 — Admin/editor threat details update failed

{
  "error": "Failed to update threat details",
  "details": "<postgres error message>"
}

500 — Catch-all

{
  "error": "Internal server error",
  "details": "<exception message>"
}

​Quick reference

​Shared errors — read endpoints

​405 — Method not allowed

​429 — IP rate limit (500 req / 15 min per IP)

​429 — Token rate limit (per-minute, tier-scoped)

​429 — Daily quota exceeded

​500 — Internal server error

​check-malicious

​401 — Missing API token

​401 — Invalid or inactive token

​400 — Invalid or missing report_type

​400 — Missing resource_identifier

​400 — Invalid repository format

​500 — Database query failed

​query-latest

​401 — Missing API token

​401 — Invalid token

​401 — Inactive token

​400 — Missing ecosystem

​500 — Query failed

​threat-feed

​401 — Missing API token

​401 — Invalid token

​401 — Inactive token

​403 — Endpoint requires Core/Pro/Enterprise

​403 — unverified=true requires Pro/Enterprise

​400 — Invalid hours

​400 — Missing ecosystem

​500 — Query failed

​threat-data

​401 — Missing API token

​401 — Invalid or inactive token

​403 — Requires Pro/Editor/Admin

​400 — Missing threat_id

​400 — Invalid UUID

​404 — Not found or not verified/modified

​false-positive

​400 — Missing ecosystem parameter

​400 — Invalid hours parameter

​400 — Invalid source parameter

​401 — Missing API token

​401 — Invalid or inactive token

​403 — Insufficient role (e.g. standard tier)

​405 — Wrong HTTP method (only GET is allowed)

​429 — IP rate limit (500 requests per 15 minutes per IP)

​429 — Token rate limit (per minute; varies by tier)

​429 — Daily quota exceeded

​500 — Threats query failed

​500 — OSV withdrawals query failed

​500 — Unexpected error (catch-all)

​query-by-username

​401 — Missing API token

​401 — Invalid token

​401 — Inactive token

​403 — Requires Pro/Enterprise

​400 — Missing params

​500 — Failed to verify permissions

​500 — Database query failed

​Write endpoints

​submit-threat-report

​401 — No Authorization header

​401 — Invalid API token (osm_...)

​429 — IP rate limit

​429 — Submission rate limit (per hour)

​403 — New-user unverified cap

​405 — Method not allowed

​400 — Missing required fields

​409 — Duplicate package in registry

​500 — Existing-package lookup failed

​500 — Threat insert failed

​500 — Threat details insert failed (threat was rolled back)

​500 — Catch-all

​modify-threat-report

​401 — No Authorization header

​401 — Invalid API token

​429 — IP rate limit (whitelisted IPs bypass)

​429 — Modification rate limit (per hour)

​405 — Method not allowed

​400 — No target identifier supplied

​404 — Lookup by package_name returned nothing

Quick reference

Shared errors — read endpoints

405 — Method not allowed

429 — IP rate limit (500 req / 15 min per IP)

429 — Token rate limit (per-minute, tier-scoped)

429 — Daily quota exceeded

500 — Internal server error

check-malicious

401 — Missing API token

401 — Invalid or inactive token

400 — Invalid or missing `report_type`

400 — Missing `resource_identifier`

400 — Invalid repository format

500 — Database query failed

query-latest

401 — Missing API token

401 — Invalid token

401 — Inactive token

400 — Missing `ecosystem`

500 — Query failed

threat-feed

401 — Missing API token

401 — Invalid token

401 — Inactive token

403 — Endpoint requires Core/Pro/Enterprise

403 — `unverified=true` requires Pro/Enterprise

400 — Invalid `hours`

400 — Missing `ecosystem`

500 — Query failed

threat-data

401 — Missing API token

401 — Invalid or inactive token

403 — Requires Pro/Editor/Admin

400 — Missing `threat_id`

400 — Invalid UUID

404 — Not found or not verified/modified

false-positive

400 — Missing ecosystem parameter

400 — Invalid hours parameter

400 — Invalid source parameter

401 — Missing API token

401 — Invalid or inactive token

403 — Insufficient role (e.g. standard tier)

405 — Wrong HTTP method (only GET is allowed)

429 — IP rate limit (500 requests per 15 minutes per IP)

429 — Token rate limit (per minute; varies by tier)

429 — Daily quota exceeded

500 — Threats query failed

500 — OSV withdrawals query failed

500 — Unexpected error (catch-all)

query-by-username

401 — Missing API token

401 — Invalid token

401 — Inactive token

403 — Requires Pro/Enterprise

400 — Missing params

500 — Failed to verify permissions

500 — Database query failed

Write endpoints

submit-threat-report

401 — No Authorization header

401 — Invalid API token (`osm_...`)

429 — IP rate limit

429 — Submission rate limit (per hour)

403 — New-user unverified cap

405 — Method not allowed

400 — Missing required fields

409 — Duplicate package in registry

500 — Existing-package lookup failed

500 — Threat insert failed

500 — Threat details insert failed (threat was rolled back)

500 — Catch-all

modify-threat-report

401 — No Authorization header

401 — Invalid API token

429 — IP rate limit (whitelisted IPs bypass)

429 — Modification rate limit (per hour)

405 — Method not allowed

400 — No target identifier supplied

404 — Lookup by `package_name` returned nothing