What is HTTP status code for a disabled REST API feature?

Question

We have REST API endpoints that all users are free to use and other endpoints that users can use if they have explicitly enabled and paid for some specific feature.

What should be the correct status code returned from the paid endpoints if it has not been enabled by the user?

I see 2 options:

1. 402 Payment required
2. 403 Forbidden

402 is described as a nonstandard client error status response code that is reserved for future use, so I do not feel like this is the right status code for this case.

Are there any other status codes that would fit this case better?

Eiser

If I was the client, 402 would make more sense to me, as it is verbosley saying what went wrong in the definition of the response code – Damask

I am not sure that it is saying that. It's saying that the payment is required but in reality, the feature could be just not enabled by the client. – Eiser

Answer 1

I'd go with the 403 Forbidden. That is what it basically boils down to. You try to access an endpoint that you do not have access to.

The fact that a user can enable it themselves doesn't change much about it. It remains forbidden as long as they don't do that.

To quote the specification:

The 403 (Forbidden) status code indicates that the server understood the request but refuses to authorize it. A server that wishes to make public why the request has been forbidden can describe that reason in the response payload (if any).

So it would definitely be good to add a response body, explaining why the error occurs and how the user can grant themselves access.

As long as 402 Payment Required is "reserved for future use", I'd avoid it. REST API's are generally accessed through scripts using libraries for making the HTTP requests. If the script doesn't recognize the 402, it could cause unexpected behavior. Most will probably do fine, but rather save than sorry.

The other 4xx status codes (which this definitely belongs to) don't apply to this scenario.

Windtight

403 is a bit misleading, as it is actually an authorization declined. And user will try to resolve his authentication problems, while this is hopeless. – Disincentive

Answer 2

The 423 HTTP Status seems to be most relevant (RFC-4986):

The HTTP 423 Locked client error response status code indicates that a resource is locked, meaning it can't be accessed. Its response body should contain WebDav information (RFC-4918).

In XML:

HTTP/1.1 423 Locked
Content-Type: application/xml; charset="utf-8" 
Content-Length: xxxx

<?xml version="1.0" encoding="utf-8" ?>
  <D:error xmlns:D="DAV:">
    <D:lock-token-submitted>
      <D:href>/workspace/webdav/</D:href>
    </D:lock-token-submitted>
  </D:error>

But I would prefer JSON body.

  { "value" : "423",
"concept" : "http:\/\/webconcepts.info\/concepts\/http-status-code\/",
"id" : "http:\/\/webconcepts.info\/concepts\/http-status-code\/423",
"description" : "Locked",
"details" : 
[ 
  { "description" : "The 423 (Locked) status code means the source or destination resource of a method is locked. This response SHOULD contain an appropriate precondition or postcondition code, such as 'lock-token-submitted' or 'no-conflicting-lock'.",
    "documentation" : "https:\/\/datatracker.ietf.org\/doc\/html\/rfc4918#section-11.3",
    "specification" : "http:\/\/webconcepts.info\/specs\/IETF\/RFC\/4918",
    "spec-name" : "RFC 4918" } ] }

Disincentive