Skip to Content
API Security TestingTroubleshooting

Troubleshooting

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

Spec Upload Issues

”Invalid JSON” Error

The uploaded file is not valid JSON. Common causes:

  • The file is in YAML format. Convert it to JSON before uploading.
  • The file contains trailing commas, comments, or other non-standard JSON syntax.
  • The file encoding is not UTF-8.

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

”Unsupported Spec Version” Error

Detectify supports OpenAPI v2 (Swagger), v3.0, and v3.1 only. 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.

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