501 Not Implemented

What is HTTP 501 Not Implemented?

Imagine you have a calculator - it's really good at adding and subtracting numbe...

HTTP 501 Not Implemented status code illustration

Explain Like I’m 3

Imagine you have a tricycle. You ask it “Can you fly to the clouds?” but the tricycle says “I’m sorry, I can’t fly! I was never built to fly. I can only ride on the ground!” That’s what 501 means - you asked the computer to do something, but the computer was never built to do that thing. It’s not broken, it just doesn’t know how to do what you asked!

Example: Asking your toy robot to make breakfast. The robot says “I don’t know how to make breakfast - I was only programmed to walk and talk!”

Explain Like I’m 5

Imagine you have a calculator - it’s really good at adding and subtracting numbers! But what if you ask it to play music? The calculator would say “I don’t have that feature! I was only built to do math, not play music.” That’s a 501 Not Implemented error. The computer received your request, but it doesn’t have the ability to do what you asked because that feature was never built into it. It’s not that you did something wrong - the computer just doesn’t have that power!

Example: Trying to use a microwave to print a document. The microwave would say “I’m not a printer! I can only heat food.”

Jr. Developer

501 Not Implemented means the server doesn’t recognize or support the HTTP method you used, anywhere on the entire server. This is different from 405 Method Not Allowed, where the server knows the method but that specific resource doesn’t allow it.

Key distinctions:

501 Not Implemented: “I don’t support PATCH anywhere on this server”
405 Method Not Allowed: “I support PATCH, but not on this specific endpoint”
404 Not Found: “This endpoint doesn’t exist”

Important RFC Requirement: Servers MUST support GET and HEAD methods. If a server returns 501 for GET or HEAD, it’s violating the HTTP specification and is misconfigured.

Common scenarios for 501:

Simple/minimal HTTP servers that only implement GET and HEAD
Sending PATCH to a server that only supports PUT for updates
Using WebDAV methods (PROPFIND, MKCOL) on non-WebDAV servers
Custom HTTP methods the server doesn’t recognize
Feature not implemented yet (though this is often server-side issue)

When to use 501:

Server doesn’t recognize the method at all
Server recognizes method but hasn’t implemented it yet
Method is not part of server’s capabilities

Use 405 instead if the server supports the method but the specific resource doesn’t allow it.

Code Example

// Express.js: Simple server that only implements GET and POST
const express = require('express');
const app = express();

// Supported methods for this simple server
const SUPPORTED_METHODS = ['GET', 'POST', 'HEAD', 'OPTIONS'];

// Middleware to check if method is implemented
app.use((req, res, next) => {
  if (!SUPPORTED_METHODS.includes(req.method)) {
    return res.status(501).json({
      error: 'Not Implemented',
      message: `${req.method} method is not implemented on this server`,
      supported_methods: SUPPORTED_METHODS,
      note: 'This is a simple server with limited HTTP method support'
    });
  }
  next();
});

// Routes that work
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

app.post('/api/users', (req, res) => {
  res.status(201).json({ message: 'User created' });
});

// These methods would return 501:
// app.put()    - PUT not implemented
// app.patch()  - PATCH not implemented
// app.delete() - DELETE not implemented

// Example: Feature not implemented yet
app.post('/api/advanced-search', (req, res) => {
  // This feature isn't built yet
  res.status(501).json({
    error: 'Not Implemented',
    message: 'Advanced search is not yet implemented',
    alternative: 'Use /api/search for basic search functionality'
  });
});

// Correct handling: 405 vs 501
app.route('/api/config')
  .get((req, res) => {
    res.json({ config: 'data' });
  })
  .all((req, res) => {
    // Config endpoint exists and server supports these methods,
    // but this specific resource only allows GET
    // So use 405, not 501
    res.status(405)
      .set('Allow', 'GET, HEAD')
      .json({
        error: 'Method Not Allowed',
        allowed_methods: ['GET', 'HEAD']
      });
  });

Crash Course

HTTP 501 Not Implemented (RFC 9110 §15.6.2) indicates the server doesn’t support the functionality required to fulfill the request. Unlike 4xx client errors, 501 is a server error (5xx) - the server’s limitations, not client mistakes, cause the failure.

RFC 9110 Definition: “The 501 (Not Implemented) status code indicates that the server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource.”

Critical Requirements:

Servers MUST support GET and HEAD (RFC 9110 §9.3.1): “All general-purpose servers MUST support the methods GET and HEAD. All other methods are OPTIONAL.”

Returning 501 for GET or HEAD is a spec violation indicating serious server misconfiguration.

Decision Tree:

Is it GET or HEAD? → Server MUST support these → Never return 501
Does server recognize the method? → No → 501 Not Implemented
Does this resource allow the method? → No → 405 Method Not Allowed
Does user have permission? → No → 403 Forbidden
Everything OK → 200/201/204 Success

501 vs 405 Distinction:

501 (Server Error):

Scope: Entire server
Meaning: “I don’t know how to handle this method anywhere”
Example: Server receives PATCH but only implements GET/POST/PUT
Responsibility: Server limitation (admin needs to add feature)

405 (Client Error):

Scope: Specific resource
Meaning: “I know this method, but not for this resource”
Example: Server supports DELETE, but this resource is read-only
Responsibility: Client using wrong method (should use allowed method)

Common Scenarios:

Minimal/Embedded Servers
- IoT devices with simple HTTP servers
- Only implement GET for status/metrics
- Return 501 for POST/PUT/DELETE
WebDAV Methods on Standard Servers
- Client sends PROPFIND, MKCOL, LOCK
- Standard HTTP server doesn’t implement WebDAV
- Retu…

Code Example

// Advanced 501 handling with method capability detection
const express = require('express');
const app = express();

// Server capability configuration
const SERVER_CAPABILITIES = {
  http_methods: ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  features: {
    webdav: false,
    http2: false,
    range_requests: true
  },
  version: 'HTTP/1.1'
};

// Method implementation registry
const implementedMethods = new Set(SERVER_CAPABILITIES.http_methods);

// Global middleware: Check if method is implemented
app.use((req, res, next) => {
  // GET and HEAD are mandatory (RFC 9110)
  if (req.method === 'GET' || req.method === 'HEAD') {
    return next();
  }

  if (!implementedMethods.has(req.method)) {
    return res.status(501)
      .set('Cache-Control', 'public, max-age=86400') // Cacheable
      .json({
        error: 'Not Implemented',
        message: `${req.method} method is not implemented on this server`,
        server_capabilities: {
          implemented_methods: Array.from(implementedMethods),
          http_version: SERVER_CAPABILITIES.version
        },
        documentation: 'https://api.example.com/docs/methods'
      });
  }

  next();
});

// WebDAV methods check
const WEBDAV_METHODS = ['PROPFIND', 'PROPPATCH', 'MKCOL', 'COPY', 'MOVE', 'LOCK', 'UNLOCK'];

app.use((req, res, next) => {
  if (WEBDAV_METHODS.includes(req.method)) {
    if (!SERVER_CAPABILITIES.features.webdav) {
      return res.status(501).json({
        error: 'Not Implemented',
        message: 'WebDAV methods are not supported',
        method: req.method,
        note: 'This is a standard HTTP server, not a WebDAV server'
      });
    }
  }
  next();
});

// Feature not implemented example
app.get('/api/v2/analytics', (req, res) => {
  // v2 analytics not built yet
  res.status(501).json({
    error: 'Not Implemented',
    message: 'v2 analytics API is not yet implemented',
    status: 'planned',
    estimated_release: '2024-Q2',
    alternative: {
      endpoint: '/api/v1/analytics',
      note: 'Use v1 analytics for now'
    }
  });
});

// Comparison: 405 vs 501
app.route('/api/readonly-resource')
  .get((req, res) => {
    res.json({ data: 'readonly data' });
  })
  .all((req, res) => {
    // Server implements these methods (POST, PUT, DELETE),
    // but THIS resource doesn't allow them
    // So use 405, not 501
    res.status(405)
      .set('Allow', 'GET, HEAD, OPTIONS')
      .json({
        error: 'Method Not Allowed',
        message: 'This resource ...

Deep Dive

HTTP 501 Not Implemented represents a fundamental aspect of HTTP’s extensibility model: servers can implement subsets of HTTP functionality while remaining compliant. Understanding 501 requires examining HTTP method semantics, server requirements, and the protocol’s evolution.

RFC 9110 Specification (Section 15.6.2):

“The 501 (Not Implemented) status code indicates that the server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource.”

Key phrase: “is not capable of supporting it for any resource” - this is a global server limitation, not resource-specific.

Mandatory vs Optional Methods:

RFC 9110 §9.1 defines method semantics:

Mandatory (MUST implement):

GET: Retrieve resource
HEAD: Like GET but without response body

Servers cannot be HTTP-compliant without implementing these.

Optional (MAY implement):

POST, PUT, DELETE, CONNECT, OPTIONS, TRACE
All other standard methods
Custom/extension methods

501 Semantics - Server vs Client Responsibility:

501 is a server error (5xx), not client error (4xx), because:

Server Limitation: The server’s implementation is incomplete/minimal
Not Client’s Fault: Client used a valid HTTP method the server simply doesn’t support
Architectural Decision: Server administrators chose not to implement certain methods
Upgrade Path: Implies server could implement method in the future

Contrast with 405 (client error): client used wrong method for a resource the server knows about.

Method Discovery and Capability Negotiation:

Clients can discover server capabilities:

OPTIONS Request: Server returns Allow header with supported methods
Trial and Error: Send request, check for 501
API Documentation: Out-of-band documentation
Well-Known URIs: /.well-known/api-capabilities (non-standard)

Caching Semantics:

RFC 9110 §15.6.2: “A 501 response is heuris cally cacheable.”

This means:

Caches can store 501 responses
Future requests for same method may return cached 501
Assumption: server capabilities rarely change
Cache-Control headers can override this

Practical Implications:

Clients receiving 501 should:

Not retry with same method (won’t suddenly be implemented)
Check for alternative methods (PUT instead of PATCH, etc.)
Document server limitation
Consider workaroun…

Code Example

// Production-grade server capability management system
const express = require('express');
const app = express();

/**
 * Server Capability Manager
 * Handles HTTP method implementation and 501 responses
 */
class ServerCapabilityManager {
  constructor(config = {}) {
    this.implementedMethods = new Set(config.methods || ['GET', 'HEAD', 'OPTIONS']);
    this.features = config.features || {};
    this.httpVersion = config.httpVersion || 'HTTP/1.1';
    this.strictCompliance = config.strictCompliance !== false;

    // Ensure GET and HEAD are implemented (RFC requirement)
    if (this.strictCompliance) {
      this.implementedMethods.add('GET');
      this.implementedMethods.add('HEAD');
    }
  }

  isMethodImplemented(method) {
    return this.implementedMethods.has(method.toUpperCase());
  }

  addMethod(method) {
    this.implementedMethods.add(method.toUpperCase());
  }

  removeMethod(method) {
    // Cannot remove GET or HEAD if strict compliance enabled
    if (this.strictCompliance && (method === 'GET' || method === 'HEAD')) {
      throw new Error(`Cannot remove ${method} - required by RFC 9110`);
    }
    this.implementedMethods.delete(method.toUpperCase());
  }

  getCapabilities() {
    return {
      http_version: this.httpVersion,
      implemented_methods: Array.from(this.implementedMethods).sort(),
      features: this.features,
      rfc_compliant: this.strictCompliance
    };
  }

  get501Response(method, requestPath) {
    return {
      error: 'Not Implemented',
      message: `HTTP method ${method} is not implemented on this server`,
      method: method,
      path: requestPath,
      server_capabilities: this.getCapabilities(),
      documentation: 'https://api.example.com/docs/http-methods',
      rfc_reference: 'RFC 9110 Section 15.6.2'
    };
  }
}

// Initialize with specific capabilities
const capabilities = new ServerCapabilityManager({
  methods: ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  features: {
    webdav: false,
    http2: false,
    range_requests: true,
    conditional_requests: true,
    compression: ['gzip', 'br']
  },
  httpVersion: 'HTTP/1.1'
});

// Middleware: Method capability check
function checkMethodImplementation(req, res, next) {
  const method = req.method.toUpperCase();

  if (!capabilities.isMethodImplemented(method)) {
    const response = capabilities.get501Response(method, req.path);

    // Log unimplemented method attempt
    console.warn('Unimplemented method requested:', {
      method,
      path: req.path,
      ip: req.ip,
      userAgent: req.get('user-agent'),
      timestamp: new Date().toISOString()
    });

    return res.status(501)
      .set('Cache-Control', 'public, max-age=86400') // Cache for 24 hours
      .json(response);
  }

  next();
}

app.use(checkMethodImplementation);

// WebDAV method detection
const WEBDAV_METHODS = new Set([
  'PROPFIND', 'PROPPATCH', 'MKCOL', 'COPY', 'MOVE',
  'LOCK', 'UNLOCK', 'ORDERPATCH'
]);

app.use((req, re...

Frequently Asked Questions

What's the difference between 501 Not Implemented and 405 Method Not Allowed?

501 means the server doesn't support the HTTP method anywhere on the entire server - it's a global server limitation. 405 means the server supports the method in general, but this specific resource doesn't allow it. Example: 501 = 'I never implement PATCH', 405 = 'I implement PATCH, but not on this read-only resource'. 501 is a server error (5xx), 405 is a client error (4xx).

Can a server return 501 for GET or HEAD requests?

No! RFC 9110 requires all HTTP servers to support GET and HEAD methods. A server returning 501 for these methods is violating the HTTP specification and is seriously misconfigured. If you encounter this, it indicates a broken or non-compliant server that needs fixing.

Should I use 501 for features that aren't built yet?

It depends. If the feature involves an unimplemented HTTP method, 501 is appropriate. But for features accessible via implemented methods (like GET/POST), consider: 503 Service Unavailable (temporary), 404 Not Found (endpoint doesn't exist yet), or 501 with explanation. Some APIs use 501 for 'coming soon' features, others prefer clearer messaging with 503 + Retry-After header.

Are 501 responses cacheable?

Yes, 501 responses are heuristically cacheable by default per RFC 9110. This means caches can store them and serve them for future requests. The assumption is that server capabilities don't change often - if a server doesn't support PATCH today, it probably won't support it tomorrow. You can override this with Cache-Control headers if needed.

What methods must an HTTP server implement?

RFC 9110 requires all general-purpose servers to implement GET and HEAD. All other methods (POST, PUT, DELETE, PATCH, OPTIONS, TRACE, CONNECT) are optional. Minimal servers (like embedded/IoT devices) might only implement GET and HEAD. Web servers typically implement at least GET, HEAD, POST, and OPTIONS.

When should I return 501 vs 404 for an unimplemented endpoint?

Use 404 when the endpoint/resource doesn't exist. Use 501 when: (1) the HTTP method itself isn't supported anywhere, or (2) you want to explicitly signal 'this feature isn't implemented yet' rather than 'this endpoint doesn't exist'. 501 suggests a server limitation, 404 suggests a wrong/missing URL. For APIs, 404 is usually clearer for missing endpoints.

How should clients handle 501 responses?

Don't retry with the same method - the server won't suddenly support it. Check if there's an alternative method that achieves the same goal (PUT instead of PATCH, POST instead of custom method). Check API documentation for supported methods. Consider workarounds (method tunneling via POST if absolutely necessary). Log the limitation for developers to address.

Common Causes

Server only implements GET and HEAD (minimal/embedded servers)
Using PATCH on server that only supports PUT for updates
Sending WebDAV methods (PROPFIND, MKCOL) to non-WebDAV server
Custom HTTP methods server doesn’t recognize
Using HTTP/1.1 methods on HTTP/1.0-only server
Server configuration explicitly disabled certain methods
Minimal server implementation for IoT/embedded devices
Feature not implemented yet (future functionality)
Legacy server doesn’t support newer HTTP methods
Server doesn’t implement optional HTTP methods
Proxy/gateway doesn’t support method forwarding
Server software missing method handlers in code

Implementation Guidance

Check API documentation for supported HTTP methods
Try alternative methods (PUT instead of PATCH, POST instead of custom method)
Verify you’re using standard HTTP methods (GET, POST, PUT, DELETE, etc.)
For WebDAV methods: confirm server has WebDAV support enabled
For custom methods: check if server has extension/plugin for that method
If building server: implement at minimum GET and HEAD (required by RFC)
If building server: add support for other standard methods as needed
Check server configuration - methods might be disabled in config files
Upgrade server software to version supporting needed methods
Use OPTIONS request to discover which methods server supports
Consider method tunneling via POST if absolutely necessary (e.g., POST with _method parameter)
For ‘coming soon’ features: communicate timeline to users, consider 503 instead

501 Not Implemented

What is HTTP 501 Not Implemented?

Explain Like I’m 3

Explain Like I’m 5

Jr. Developer

Code Example

Crash Course

Code Example

Deep Dive

Code Example

Frequently Asked Questions

What's the difference between 501 Not Implemented and 405 Method Not Allowed?

Can a server return 501 for GET or HEAD requests?

Should I use 501 for features that aren't built yet?

Are 501 responses cacheable?

What methods must an HTTP server implement?

When should I return 501 vs 404 for an unimplemented endpoint?

How should clients handle 501 responses?

Common Causes

Implementation Guidance

Related Status Codes

Comments