Error Handling

The URL Media Inspector API follows standard HTTP status codes and returns a structured error format.

Error Response Format

When an error occurs, the API returns a standardized JSON structure.

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE_HERE",
    "message": "Human readable error description."
  }
}

Common Error Codes

HTTP Status	Error Code	Description
400	INVALID_URL	The provided URL string was malformed.
400	INVALID_PAYLOAD	The request body did not match the expected schema.
403	SSRF_BLOCKED	The resolved IP address maps to an internal subnet.
404	RESOURCE_NOT_FOUND	The remote server returned a 404 response.
408	UPSTREAM_TIMEOUT	The remote server took too long to respond.
413	PAYLOAD_TOO_LARGE	The remote file exceeds the configured size limit.
502	BAD_GATEWAY	The remote server returned an invalid or unparseable response.

Technical Notes

• Client errors (4xx) generally indicate an issue with the provided URL or payload.
• Upstream errors (like timeouts or 502) indicate an issue with the target remote server, not the media inspector infrastructure.