Error Codes

This page lists the possible error codes returned by the Unwanted Traffic API, along with their meanings and example responses. All error responses are in JSON format with a status of "error" and a message describing the issue.

Error Codes Overview

The API uses standard HTTP status codes to indicate errors. The table below summarizes the possible error codes:

HTTP Status Code	Meaning	Description
400	Bad Request	The request is malformed or contains invalid parameters.
401	Unauthorized	The API key is missing or invalid.
403	Forbidden	The API key does not have permission to access the requested resource.
404	Not Found	The requested resource (e.g., session, attempt, or malware record) does not exist.
429	Too Many Requests	The rate limit has been exceeded (100 requests/minute for most endpoints, 50 requests/minute for /sessions, /attempts, /malware).
500	Internal Server Error	An unexpected server error occurred.

Example Error Responses

Below are example error responses for each error code.

400 Bad Request

Returned when the request contains invalid parameters, such as an incorrectly formatted filter or missing required fields.

Example Response:

{
  "status": "error",
  "message": "Invalid filter format: JSON parsing error"
}

401 Unauthorized

Returned when the X-API-Key header is missing or the provided API key is invalid.

Example Response:

{
  "status": "error",
  "message": "Invalid or missing API key"
}

403 Forbidden

Returned when the API key does not have permission to access the requested endpoint or resource.

Example Response:

{
  "status": "error",
  "message": "Access forbidden: Insufficient permissions"
}

404 Not Found

Returned when the requested resource (e.g., a specific session, attempt, or malware record) does not exist.

Example Response:

{
  "status": "error",
  "message": "Session not found"
}

429 Too Many Requests

Returned when the rate limit is exceeded. The response may include a Retry-After header indicating when to retry.

Example Response:

{
  "status": "error",
  "message": "Rate limit exceeded. Please try again later."
}

500 Internal Server Error

Returned when an unexpected server error occurs. Contact the API administrator if this persists.

Example Response:

{
  "status": "error",
  "message": "Internal server error. Please try again later."
}

Handling Errors

To handle errors effectively:

• Check the status field in the response. If it is "error", inspect the message for details.
• For 429 errors, implement exponential backoff or respect the Retry-After header.
• Ensure the X-API-Key header is included and valid to avoid 401 errors.
• Validate query parameters and filter formats to prevent 400 errors.
• For persistent 500 errors, contact the API administrator.