title: REST API response codes in case of failed business logic but successful resource creation
body: <p>I am looking for advise on the design of an API that processes payments. Only one resource type is exposed by the API, named "payment".</p>
  
  <p>The caller (which is typically another backend) can</p>
  
  <pre><code>PUT /payments/{id}
  </code></pre>
  
  <p>in order to initiate a payment (which can succeed or fail at various stages, now and later).</p>
  
  <p>If the request is malformed (missing mandatory fields, credit card numbers with too few digits, etc.), we'll send a <code>400 bad request</code> and exit here. </p>
  
  <p>Assuming the request is well-formed, the business logic of the <code>PUT</code> request triggers further actions synchronously which, in some cases and depending on the payment method (credit card, PayPal, etc.), can lead to the payment being declined immediately. The caller should be unaware of the details, and there are only three relevant outcomes from their perspective:</p>
  
  <ol>
  <li><p>We already know that the payment is declined (e.g. because the credit card network declined the amount). The end-user (browser) should be redirected to an error page.</p></li>
  <li><p>In order to proceed, the end-user needs to be redirected to a 3rd party page, such as the PayPal checkout page, to confirm the payment.</p></li>
  <li><p>The client can go ahead with the order process for now, with no further user interaction required. The end-user (browser) should be redirected to a success page. (This is usually not an actual "success" yet, it is merely a "no-error-yet". Later on, we will try to collect the actual money, e.g. by charging the credit card; this may fail or succeed, and eventually we will inform the caller asynchronously; but for now, all is good.)</p></li>
  </ol>
  
  <p>It is important that the resource at the URL receiving the <code>PUT</code> is always created, no matter whether or not the failure of the payment is immediately recognized, such that the caller can issue a subsequent</p>
  
  <pre><code>GET /payments/{id}
  </code></pre>
  
  <p>and will return a representation of the payment with all kinds of information, most importantly the status:</p>
  
  <pre><code>{
     "payment-method": "...",
     "amount": ...,
     ...
     "status": "OPEN"
  }
  </code></pre>
  
  <p><strong>Questions:</strong></p>
  
  <ul>
  <li>In the cases above, in particular case 1 (payment declined), what HTTP status codes should be
  returned? In particular, note that in a sense, this is an error (the payment
  was declined) and a success (the resource was created) at the same
  time.</li>
  <li>If the status codes are not unique for each case, how should we
  signal to the client which of the three outcomes occurred?</li>
  </ul>
  
  <p><strong>Edit: Potential answers</strong></p>
  
  <p>There are two potential answers, both of which have merits. Basically what I want to get at is whether we should return a 2xx or 4xx in case of a declined payment.</p>
  
  <ul>
  <li><p>Potential answer 1: If the payment is declined, this is an error and the service should return a 4xx such as <code>409 conflict</code> to signal that the payment was not successful. The other two cases should return a 3xx (redirect) or <code>201 created</code>. This makes it easy for the caller to decide how to continue, based on the status code.</p></li>
  <li><p>Potential answer 2: In all three cases, the <code>payment</code> resource is created and available via <code>GET</code> afterwards. Therefore, the API should always signal this as a success, e.g. as a <code>201 created</code> or <code>202 accepted</code>. Also, it is not the caller (=backend service) who should be redirected, but the end-user's browser; the <code>payment</code> resource would not be found at the redirection target; therefore case 2 should also not return a 3xx. A <code>4xx</code> should only be returned if the client has messed up the call syntactically, etc. Client code should make the decision on how to proceed not based on the HTTP status, but based on the <code>status</code> field in the payload.</p></li>
  </ul>
  
  <p>Which is more appropriate?</p>