6

I have a RESTful API that is used by another internal application that post updates to it.

The problem is that some unexpected peaks occur and, during those times, a request might take longer than 60 seconds (the limit defined by the load balancer, which I cannot change) to respond, which causes a 504 Gateway Timeout error.

When the latter application gets such response, it will retry the request again after 10 minutes or so.

This caused some requests to be processed twice, because the first request was successful, but took more than 60 seconds.

So I decided to use Idempotency Keys in the requests to avoid this problem. The issue is that I don't know what I should return in this case.

Should I just stick with 200 OK? Should I return some 4xx code?

1
  • 1
    If your API is documented to be idempotent, then 200 OK is the correct code. Note REST typically uses PUT for idempotent operations, but POST is for arbitrary processing, which can be idempotent if documented. Aug 2, 2018 at 15:32

2 Answers 2

9

I'd say it highly depends if it is an error for you or not. But I'd say the exact response code is more a matter of taste rather than best practice. But since I guess you're rejecting the duplicated requests, you want to report an error code such as 409 Conflict:

Indicates that the request could not be processed because of conflict in the current state of the resource, such as an edit conflict between multiple simultaneous updates.

https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_errors

Whenever a resource conflict would be caused by fulfilling the request. Duplicate entries and deleting root objects when cascade-delete is not supported are a couple of examples.

https://www.restapitutorial.com/httpstatuscodes.html

3
  • 1
    This code [409] is used in situations where the user might be able to resolve the conflict and resubmit the request. datatracker.ietf.org/doc/html/rfc7231#section-6.5 But the question mentions that the first request was successful and therefore shouldn't be resubmitted. 409 may therefore not be suitable for this use case. Jul 28, 2022 at 15:56
  • @MoritzKampfinger What's your alternative then? From my POV, I think the choice of the HTTP code used is highly subjective from time to time and one would choose the one which is the best match. I think due to the might a 409 should be completely fine, because that implies that this condition doesn't have to be met. I however strongly advice not to send success codes for an unsuccessful request.
    – maio290
    Jul 28, 2022 at 20:38
  • I completely agree with all your points. Nevertheless, the RFC states, that 409 is used in cases, where there is a conflict, which has to be solved before resubmitting the request. This is not the case in the above example. Since the state of the requested server has been already successfully updated by the first request. in my opinion, the second request to this server should return a 2xx. But as you said: This is highly subjective and I wouldn't blame anyone for choosing some other response code. Aug 10, 2022 at 7:21
3

A potentially useful reference is RFC 5789, which describes the PATCH method. Obviously, you aren't doing a patch, but the error handling is analogous.

For instance, if you were sending a JSON Patch document, then you might be ensuring idempotent behavior by including a test operation that checks that the resource is in the expected initial state. After your operation, that check would presumably fail. In that case, the error handling section directs your attention to RFC 5789 -- section 2.2 outlines a number of different possible cases.

Another source of inspiration is to look at RFC 7232 which describes conditional requests. The section on If-Match includes this gem:

An origin server MUST NOT perform the requested method if a received If-Match condition evaluates to false; instead, the origin server MUST respond with either a) the 412 (Precondition Failed) status code or b) one of the 2xx (Successful) status codes if the origin server has verified that a state change is being requested and the final state is already reflected in the current state of the target resource (i.e., the change requested by the user agent has already succeeded, but the user agent might not be aware of it, perhaps because the prior response was lost or a compatible change was made by some other user agent).

From this, I infer that 200 is completely acceptable if you can determine that the work was already done successfully.

Your Answer

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

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