Let's assume we have a required attribute foo for an API call. This can have valid values of 1 and 2 which denote some valid option in the system.

Since this field accepts an integer, if we provide other integers like 3, 4, 5 we get a 406 code with a message like foo cannot be XXXX in response header.

Now, XXXX is another valid payment type in the system. Just not valid for the current use case.

Should this (i.e. other valid values in the system) be hidden from the client with a generic error like Invalid payment type or this is acceptable behavior.

What could be valid security concerns with this approach?

  • What would the response be if someone provides a value like 100 that does not match any valid payment type? Do you then also return a 406 code with "foo cannot be 100"? – Bart van Ingen Schenau Sep 11 at 7:51
  • Are you effectively asking if it's okay to use "invalid" when you mean "invalid in this particular case" instead of "always invalid"? Or am I misunderstanding the question? – Flater Sep 11 at 8:30
  • @Bartvaningenschenau - Currently status that is not valid just throws 500 Internal server error. But this is obviously bad. And hence was seeking the correct option. – Gaurav Singh Sep 12 at 5:26
  • @Flater My question was is it okay to hide any other payment type which is not valid for the current use case. For instance, 20 might represent something valid but is invalid for the current flow and hence, is it advisable to just say. payment type invalid instead of telling what 20 even means in the system. – Gaurav Singh Sep 12 at 5:29
  • @GauravSingh: From a security perspective, you don't want to inform attackers that there might be a difference between "not valid for current flow" and "I don't know what you mean with that number", so both should get the same error response. – Bart van Ingen Schenau Sep 12 at 6:32

Interface Design

Regardless of if this interface is inside your code, a command line, a gui, a script engine, or whatever the important thing is the user.

Fortunately code once written is incredibly patient and will use even the most torturous interface. However it still takes a human to write that code. To that end what you really want to do is guide the user into correctly using your interface.

Consider a skipping rope. Imagine you had never seen one before, how would you figure out how to use it? I suppose those things on the end look like hand grips... maybe they need to be held? If you hold them they probably feel comfortable. Also notice that holding the rope itself is generally uncomfortable. Feedback that something is off.

Same principle applies to your web api. If a request comes in that is incorrect the response should guide the user toward the correct usage.

  • It should provide some form of negative feedback to dissuade continuing further without thinking.
  • Some information about what is wrong is the next step.
  • Finally, direction toward correct usage.

Without direction your user can only experience frustration - as they are being punished (the negative feedback) without a reasonable prospect of avoiding that on their next attempt.


Going to your example.

  1. The request fails, and they are told: no payment XXXX is invalid.


  • They are not told which parameter failed.
  • They are not told in like terms. They gave a number, but the reply is some label. What does that even mean?
  • They are not told how to fix the problem. Should they use the label instead? Try random numbers?

  1. The request fails, and they are told: Invalid payment type

This is marginally better. At least they aren't confused by a random unassociated label.

But still how should they proceed? Do they try other random numbers? Try writing in the label instead?

What's Better?

  1. The request fails, and they are told:

 Payment type can only be 1 or 2.
   - 1 is for XXXX payments
   - 2 is for YYYY payments.

 Remember that a payment type of 2 requires arg23 be set to ABC, DEF, or GHJ, see [link].
 arg23 is optional for a payment type of 1.

  • The user is shown where the problem is in their own usage.
  • Why this is a problem is explained
  • The correct usage is indicated, and further explained.
  • A further common issue is highlighted
  • If they are still confused there is a link to somewhere that hopefully has more information.

This is a much better response overall. Its also harder to get right, and what's right will probably change overtime.

  • Thanks. Your answer is quite informative. – Gaurav Singh Sep 12 at 6:19

It shouldn't matter.

  1. The full list of possible payment types should be known to the user. It's either part of the client software/library, part of the api documentation or another call returns the full list.

  2. The client should be able to perform validation. If payment type X is not valid for some combination of things I would expect the client to throw and error prior to sending the request to the api.

  3. You should not be relying on security through obscurity. A hacker will send every possible combination of parameters. Don't have secret ones that you just hope people wont send unless they have been told about them.

  • I agree to point three. If there is an interface someone will use it inventively. – Kain0_0 Sep 13 at 4:09

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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