Error Codes¶

The CyberShield API returns structured error responses to help you diagnose authentication issues, invalid requests, server errors, and rate limits.
This page lists all common error codes along with their causes and recommended fixes.

Error Response Format¶

All errors follow a consistent JSON structure:

{
  "status": "error",
  "code": "401",
  "message": "Unauthorized: Invalid API key"
}

Client-Side Errors (4xx)¶

These errors occur due to missing data, invalid input, or incorrect authentication.

Code	Meaning	Description	How to Fix
400 – Bad Request	Invalid request	Missing fields, invalid hash format, unsupported parameters	Verify request body; send valid SHA-256 hash
401 – Unauthorized	Invalid or missing API key	Token missing, expired, or malformed	Add `Authorization: Bearer <API_KEY>`
403 – Forbidden	Key lacks permission	API key valid but insufficient privileges	Check role, environment (Prod/Sandbox)
404 – Not Found	Resource not found	Unknown scanId or missing report	Ensure file/hash was submitted first
409 – Processing	Scan not finished	Report requested before scan completes	Retry after a delay
413 – Payload Too Large	File exceeds size limit	Upload limit exceeded	Compress or reduce file size
415 – Unsupported Media Type	File type not allowed	Wrong MIME type	Use supported file formats
429 – Too Many Requests	Rate limit exceeded	Too many API calls in a short time	Use retries or reduce request volume

Server-Side Errors (5xx)¶

These indicate temporary issues on the CyberShield backend.

Code	Meaning	Description	How to Fix
500 – Server Error	Internal failure	Unexpected backend issue	Retry after some time
503 – Service Unavailable	API temporarily offline	Maintenance or temporary outage	Retry with exponential backoff

Example Error Response¶

{
  "status": "error",
  "code": "404",
  "message": "Scan ID not found."
}

When Errors Occur Most Commonly¶

Operation	Possible Errors
Scan File	401, 413, 415, 429
Submit Hash	400, 401, 404
Get Report	400, 401, 404, 409

Final Notes¶

You have now reached the end of the CyberShield API Reference.
With authentication, core endpoints, report retrieval, and error handling covered, you should be fully equipped to integrate CyberShield's security capabilities into your applications. Use these APIs to automate scanning, streamline verification workflows, and enhance the security posture of your systems.