Question

I have a REST endpoint accepting a POST request to mark a code as redeemed. The code can only be redeemed between certain dates.

How should I respond if someone attempts to redeem the code early?

I suspect HTTP 403, Forbidden, is the right choice but then the w3c states that “the request SHOULD NOT be repeated” whereas in this case I would anticipate the request being repeated, just at a later date.

Answer 1

409 Conflict

The request could not be completed due to a conflict with the current
state of the resource. This code is only allowed in situations where
it is expected that the user might be able to resolve the conflict and
resubmit the request. The response body SHOULD include enough
information for the user to recognize the source of the conflict.
Ideally, the response entity would include enough information for the
user or user agent to fix the problem; however, that might not be
possible and is not required.

403 Forbidden makes more sense if they are trying to redeem a coupon that has already been redeemed, though 410 Gone seams elegant in this situation as well.

404 Not Found isn’t ideal because the resource does in fact exist, however you can use it if you don’t want to specify a reason with the 403 or if you want to hide the existence of the resource for security reasons.

If you are using HATEOAS, then you can also head you clients off at the pass (so to speak) by only including a redeem hypermedia control in the coupon resource (retrieved via a GET) when the coupon can be redeemed; though this won’t stop overly bound clients from trying to redeem it anyway.