Introduction

APIs that support versioning through the Accept header (e.g., Accept: application/vnd.myapi.v2+json) return a 406 Not Acceptable error when the client requests a version that is not available. This commonly occurs after older API versions are deprecated and removed, or when clients are misconfigured with incorrect version strings.

Symptoms

  • API returns 406 Not Acceptable with version mismatch error
  • Client requests work after removing the version from the Accept header
  • Error correlates with a recent API version deprecation
  • Error message: {"error":"not_acceptable","message":"Requested API version v1 is no longer available. Use v2 or v3."}
  • API documentation lists different versions than what the client is requesting

Common Causes

  • Client hardcoded an API version that has been deprecated and removed
  • Accept header format incorrect (e.g., v=2 instead of vnd.myapi.v2+json)
  • API version deprecation completed without client notification or migration window
  • Client library outdated and using an old default API version
  • API gateway not configured with the correct version routing rules

Step-by-Step Fix

  1. 1.Check the current API version request and available versions: Identify the mismatch.
  2. 2.```bash
  3. 3.# Check what the client is requesting
  4. 4.curl -v -H "Accept: application/vnd.myapi.v1+json" https://api.example.com/resource
  5. 5.# Response: 406 Not Acceptable

# Check available versions (often via OPTIONS or a versions endpoint) curl -s https://api.example.com/versions | jq '.available_versions' # Returns: ["v2", "v3"] ```

  1. 1.Update the client to use an available API version: Fix the Accept header.
  2. 2.```bash
  3. 3.# Use the latest stable version
  4. 4.curl -H "Accept: application/vnd.myapi.v3+json" https://api.example.com/resource
  5. 5.# Or use the default version (no Accept header needed)
  6. 6.curl https://api.example.com/resource
  7. 7.`
  8. 8.Update API client libraries to the latest version: Ensure the library uses the correct version.
  9. 9.```bash
  10. 10.# Update the API client package
  11. 11.pip install --upgrade myapi-client # Python
  12. 12.npm update @mycompany/api-client # Node.js
  13. 13.go get github.com/mycompany/api-go-client@latest # Go
  14. 14.`
  15. 15.Implement API version negotiation with fallback: Handle version mismatches gracefully.
  16. 16.```python
  17. 17.# Client-side version negotiation
  18. 18.def api_request(endpoint, preferred_version="v3"):
  19. 19.versions_to_try = [preferred_version, "v2", "default"]
  20. 20.for version in versions_to_try:
  21. 21.headers = {"Accept": f"application/vnd.myapi.{version}+json"} if version != "default" else {}
  22. 22.response = requests.get(f"https://api.example.com/{endpoint}", headers=headers)
  23. 23.if response.status_code != 406:
  24. 24.return response
  25. 25.raise Exception("No compatible API version available")
  26. 26.`
  27. 27.Verify the API works with the correct version: Test the fix.
  28. 28.```bash
  29. 29.curl -H "Accept: application/vnd.myapi.v3+json" https://api.example.com/resource | jq '.'
  30. 30.# Should return 200 OK with the expected response
  31. 31.`

Prevention

  • Communicate API version deprecations well in advance (minimum 6 months notice)
  • Provide a migration guide for each API version change
  • Support a default version (no Accept header required) for backward compatibility
  • Implement version negotiation that suggests available versions in 406 responses
  • Monitor API version usage and contact clients using deprecated versions
  • Use API versioning that includes the version in the URL path as a fallback mechanism