< HTTP/1.1 501 Not Implemented

TL;DR: Server doesn’t support the requested functionality (like unsupported HTTP methods). Use a supported method or upgrade the server software.

What is a 501 Error?

A 501 Not Implemented status code means the server doesn’t recognize the request method or lacks the ability to fulfill the request. Think of it like asking a basic calculator to solve calculus—it understands that you’re asking it to do math, but it simply doesn’t have the capability to perform that specific operation.

The server acknowledges the request but doesn’t support the functionality required to complete it.

When Does This Happen?

You’ll encounter a 501 error in these common situations:

1. Unsupported HTTP Methods

You use:      PATCH /api/users/123
Server:       Only supports GET, POST, PUT, DELETE
Result:       501 Not Implemented

2. Missing Feature Implementation

You request:  GET /api/v2/advanced-search
Server:       v2 API not yet implemented
Result:       501 Not Implemented

3. Disabled Server Features

You try:      PUT /upload/large-file
Server:       File upload feature disabled
Result:       501 Not Implemented

4. Protocol Version Issues

You use:      HTTP/2 specific features
Server:       Only supports HTTP/1.1
Result:       501 Not Implemented

5. Custom Method Not Supported

You send:     CUSTOM /api/special-action
Server:       Doesn't recognize CUSTOM method
Result:       501 Not Implemented

Example Response

When functionality isn’t implemented, the server responds like this:

HTTP/1.1 501 Not Implemented
Content-Type: application/json
Allow: GET, POST, PUT, DELETE
Content-Length: 156

{
  "error": "Not Implemented",
  "message": "The PATCH method is not supported for this resource",
  "supported_methods": ["GET", "POST", "PUT", "DELETE"],
  "documentation": "https://api.example.com/docs"
}

Key parts of this response:

• 501 Not Implemented - The status code and reason
• Allow header - Lists the methods that ARE supported
• Content-Type - Format of the error response
• Body - Details about what’s not implemented and alternatives

Real-World Examples

Example 1: Unsupported HTTP Method

PATCH /api/users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Updated Name"
}

Response:

HTTP/1.1 501 Not Implemented
Content-Type: application/json
Allow: GET, POST, PUT, DELETE

{
  "error": "Method not implemented",
  "message": "PATCH method is not supported",
  "supported_methods": ["GET", "POST", "PUT", "DELETE"],
  "alternative": {
    "method": "PUT",
    "description": "Use PUT to update the entire resource",
    "example": "PUT /api/users/123 with complete user object"
  }
}

Example 2: Feature Not Yet Implemented

GET /api/v3/analytics/advanced HTTP/1.1
Host: api.example.com
Authorization: Bearer token123

Response:

HTTP/1.1 501 Not Implemented
Content-Type: application/json

{
  "error": "Feature not implemented",
  "message": "Advanced analytics API is not yet available",
  "status": "planned",
  "estimated_release": "Q2 2024",
  "alternatives": [
    {
      "endpoint": "/api/v2/analytics/basic",
      "description": "Basic analytics are available"
    }
  ],
  "roadmap": "https://api.example.com/roadmap"
}

How to Handle 501 Errors

As a Developer:

• Check the Allow header for supported methods
• Look for alternative endpoints or methods
• Update your code to use supported functionality
• Consider implementing fallback behavior

As an API Consumer:

• Read the API documentation for supported features
• Use alternative methods suggested in the response
• Check for API version compatibility
• Plan for feature availability in your application

501 vs Other Similar Codes

Code	Meaning	What’s Different
501	Server doesn’t support this functionality	Feature/method not implemented
405	Method not allowed	Resource exists but method not allowed for it
404	Not found	Resource/endpoint doesn’t exist
500	Internal server error	Server error while processing
503	Service unavailable	Server temporarily can’t handle requests

Common Implementation Scenarios

❌ Returning 404 for unimplemented features

// Wrong - this hides that the endpoint exists
app.patch('/api/users/:id', (req, res) => {
  res.status(404).json({ message: 'Not found' })
})

✅ Proper 501 for unimplemented methods

// Correct - clearly indicates feature not implemented
app.patch('/api/users/:id', (req, res) => {
  res.status(501).json({
    error: 'Not implemented',
    message: 'PATCH method not yet supported',
    supported_methods: ['GET', 'POST', 'PUT', 'DELETE'],
    alternative: 'Use PUT to update the entire resource'
  })
})

❌ Generic error for missing features

// Not helpful to developers
app.get('/api/v2/advanced', (req, res) => {
  res.status(500).json({ message: 'Error' })
})

✅ Clear 501 with roadmap information

// Helpful and informative
app.get('/api/v2/advanced', (req, res) => {
  res.status(501).json({
    error: 'Feature not implemented',
    message: 'Advanced API v2 is under development',
    status: 'in_progress',
    estimated_completion: '2024-Q2',
    current_alternative: '/api/v1/basic',
    subscribe_updates: '/api/notifications/subscribe'
  })
})

Server Implementation Examples

Express.js method handling:

// Handle unsupported methods gracefully
app.use('/api/users/:id', (req, res, next) => {
  const supportedMethods = ['GET', 'POST', 'PUT', 'DELETE']

  if (!supportedMethods.includes(req.method)) {
    return res
      .status(501)
      .set('Allow', supportedMethods.join(', '))
      .json({
        error: 'Method not implemented',
        message: `${req.method} method is not supported`,
        supported_methods: supportedMethods
      })
  }

  next()
})

Feature flag implementation:

// Use feature flags for gradual rollouts
app.get('/api/beta-feature', (req, res) => {
  if (!featureFlags.isBetaFeatureEnabled()) {
    return res.status(501).json({
      error: 'Feature not available',
      message: 'Beta feature is not enabled for your account',
      status: 'beta',
      request_access: '/api/beta/request-access'
    })
  }

  // Feature implementation...
})

When to Use 501 vs 405

Use 501 Not Implemented when:

• The server doesn’t support the HTTP method at all
• A feature is planned but not yet built
• Functionality is disabled server-wide
• The server lacks the capability to fulfill the request

Use 405 Method Not Allowed when:

• The resource exists but doesn’t support that specific method
• The method is valid but not allowed for this particular resource
• You want to indicate which methods ARE allowed

API Versioning and 501

// Handle API version compatibility
app.use('/api/v3/*', (req, res, next) => {
  res.status(501).json({
    error: 'API version not implemented',
    message: 'API v3 is not yet available',
    current_version: 'v2',
    migration_guide: '/docs/v2-to-v3-migration',
    v2_endpoint: req.url.replace('/v3', '/v2')
  })
})

Try It Yourself

Visit our request builder and test unimplemented features:

1. Set method to PATCH
2. Set path to /api/unsupported
3. Send the request
4. Examine the 501 response with supported alternatives

Try it with curl

Send a method the server does not recognize.

curl -i -X FOOBAR https://api.example.com/items

Example output (illustrative, not captured from a real server):

HTTP/1.1 501 Not Implemented
Content-Type: text/plain

Many servers answer an unknown method with 405 or 400 instead, so 501 is not guaranteed.

Related Status Codes

• 405 Method Not Allowed - Method not allowed for this resource
• 404 Not Found - Resource doesn’t exist
• 500 Internal Server Error - Server processing error
• 503 Service Unavailable - Server temporarily unavailable