According to the MDN the http protocol has the 402 status code:


And is used for methods that require payment.

Also RFC 2616 states:

This code is reserved for future use.

In my case I want to perform an api for doctor appointment system the idea is that I have an API consumed by my clients:

PUT /appointment

Where it has the following input:

date: The appointment date

time: The appointment time

doctor_id: The id of the doctor that user needs to perform the appointment.

The method above will save an appointment. But some doctors required to be payed beforehand the appointment. Therefore, as a solution I thought to return a 402 response status indicating to the client that in order to save the response needs a payment.

The response will return the following:

  'appointment_id': // Id of the appointment,
  'date': // Appointment date,
  'time': // Appointment time,
  'doctor_name': //The name of the doctor,
  'payment_link': //The payment link

In my system I store the appointment in the following table:

  'appointment_id': SERIAL UNSIGNED INTEGER PK
  'date': DATE
  'time': TIME
  doctor_id: INTEGER
  status:L enum [appointed,canceled,didnt_show,requires_payment]

with status requires_payment.

But as both mdn and RFC-2616, the 402 http stsatus code, is an expiremental one, therefore I wonder if is it safe for use.

Is it a widespread http status code despite being expiremental? And is it good idea to use it despite being expiremental?

1 Answer 1


No. 402 is quite non-standard, but if it was used, it would be used if a payment was required to connect to the server, and you couldn't connect to the server because you didn't pay for access to the server.

In your situation, you can access the server. You do get the information from the server that you want. There is no error. This is a plain status 200.

As a guideline, if you didn't do an http request, but went in person to the doctor's office and got an answer, then the https request should give a status 200 and a body containing exactly the information that the doctor or his receptionist would give you in person. If the receptionist refuses to talk to people without a face mask, that's a status 401. You come back with a face mask and try again. If the receptionist tells you the office is not available to the public and calls the police for trespassing, that's a status 403.

Http status is only about the communication with the server, not about what's in the answer. As long as the server gives the correct answer, it is a status 200.

PS. In your link, the descriptions for 403 and 404 look a bit dubious. 403 means "I'm not telling you whether the resource exists or not, but if it did, you would never be allowed to access it. Don't bother trying". 404 should not be used instead of 403 to hide the existence of a forbidden resource, because 403 doesn't reveal the existence in the first place.

  • So I should use http body in case to indicate that a payment is required right? Commented Jan 21, 2022 at 11:37
  • In my case I do save the appointment with an internal status require payment in that case what http status code is suitable? Commented Jan 21, 2022 at 11:41
  • 2
    Yes, you should just use the http body to give the caller all the information that they need. Basically, is this information that you would get if you knocked on the doctor's door and got an answer in person? In that case it is status 200. The doctor would tell you that you have to pay before you get an appointment, so put it in the body and give it status 200.
    – gnasher729
    Commented Jan 21, 2022 at 11:41
  • Therefore 402 is more suitable to indicate for systems eg. that require a monthly subscription in order to be accessed eg. a cloud provided that in order to list your vms needs to be payed, right? Commented Jan 21, 2022 at 11:46
  • 1
    Yes, that kind of thing where you pay just for the privilege to talk to the server could give an error 402. If there is a combination (like you didn't pay for the server access, you are not authenticated, and the resource is forbidden) you'd likely get 402 without authentication etc. being checked; if you paid the bill you'd probably get 401 if not authenticated even if the access is forbidden, if you are authenticated you'd get 403 if access is forbidden, whether the resource exists or not, and if access is allowed you'd finally get either 200 or 404.
    – gnasher729
    Commented Jan 21, 2022 at 11:53

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.