Skip to Content
API Security TestingTroubleshooting

Troubleshooting

This page covers common issues you may encounter with API Scanning and how to resolve them.

Spec Upload Issues

”Invalid File” Error

The uploaded file is not valid JSON or YAML. Common causes:

  • The file contains trailing commas, comments, or other non-standard syntax.
  • The file encoding is not UTF-8.

Fix: Validate your file with a linter (such as jq . openapi.json for JSON or a YAML validator for YAML files) and correct any syntax errors.

”Unsupported Spec Version” Error

Detectify supports OpenAPI v2 (Swagger), v3.0, and v3.1. If your spec uses a different format or an older Swagger version, it will not be accepted.

Fix: Ensure your spec includes the correct version field ("swagger": "2.0" or "openapi": "3.0.x" / "openapi": "3.1.x").

”Unresolved References” Error

Your spec contains $ref references to external files that cannot be resolved. Detectify does not fetch external references during parsing.

Fix: Bundle your spec into a single file with all references inlined. Tools such as swagger-cli bundle or redocly bundle can do this automatically.

No Endpoints Detected

The parser completed without errors but found no scannable endpoints.

Fix: Verify that your spec has entries under the paths object with at least one HTTP method defined for each path.

Authentication Issues

Scanner Receives 401 or 403 Responses

The scanner cannot authenticate with your API.

  • API Key: Verify the header name and value are correct. Check whether the key has expired.
  • Basic Auth: Confirm the username and password are valid.
  • OAuth 2.0: Ensure the token endpoint, client ID, client secret, and scopes are correct. Test the OAuth flow manually to confirm it works.

Token Expiration During Scan

If your API uses short-lived tokens without OAuth 2.0 auto-refresh, the scanner may lose authentication mid-scan.

Fix: Configure OAuth 2.0 with a token endpoint so the scanner can refresh tokens automatically. Alternatively, use a long-lived API key for scanning purposes.

Scan Performance Issues

Scan Takes Too Long

Long scan times are usually caused by:

  • Large number of endpoints. APIs with hundreds of endpoints naturally take longer. Consider narrowing the scan scope if you want faster results.
  • Strict rate limiting. Very low request rate limits extend scan duration significantly.
  • Slow API responses. If your API takes several seconds to respond, each payload takes proportionally longer.

Scan Produces No Findings

A scan with zero findings does not necessarily mean your API is secure. Possible reasons include:

  • Authentication failure. If the scanner cannot authenticate, it only tests unauthenticated endpoints, which may have no vulnerabilities.
  • Incomplete spec. Endpoints not defined in the spec are not tested.
  • Rate limiting or WAF blocking. If your WAF blocks scanner traffic, payloads never reach the API. See Network Setup for allowlisting instructions.
  • Selected operations are misconfigured. If an operation has been selected as a part of the scope, but missing or invalid example values mean no functioning API calls can be generated and as such fuzzing capabilities and results are reduced.

Getting Help

If you encounter an issue not covered here, contact Detectify support through the dashboard or at support.detectify.com .

Last updated on
ResultsOverview