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?

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.