HTTP status codes

this page explains the http status codes returned by cross river apis and provides guidance on how to handle each status code, including when and how to retry requests using idempotency keys status codes reference code status explanation recovery 200 ok the request has succeeded n/a 400 bad request the request was not processed due to something the server considers to be a client error typically due to malformed request syntax, invalid request message framing, or deceptive request routing fix the request and retry using the same idempotency key 401 unauthorized the request was not processed because it lacks valid authentication credentials (api key) for the requested resource obtain a new token and retry using the same idempotency key 403 forbidden the request was not processed because api key doesn't have permission to perform the request if your permissions are updated then retry using the same idempotency key 404 not found the request was not processed because the server cannot find the requested resource common causes of 404 responses are mistyped urls or pages that are moved or deleted without redirection fix the request and retry using the same idempotency key 408 request timeout the request was not processed because we were unable to respond before your server closed its connection we recommend keeping connections open for at least 30 seconds retry using the same idempotency key 409 conflict the request conflicts with another request (perhaps due to using the same idempotent key) retry using the same idempotency key see handling a cached response docid\ o5lkhhubbs7rmu7pxvsjp 424 external dependency failed the request was not processed due to a failure in a dependency external to cross river fix root cause and retry using the same idempotency key 429 too many requests the request was not processed because your client has sent too many requests in a given amount of time slow down the rate of requests retry using the same idempotency key 5xx server errors something went wrong on cross river's end retry using the same idempotency key see handling cached responses docid\ o5lkhhubbs7rmu7pxvsjp handling cached responses the clientidentifier parameter allows you to determine the outcome of a request when a cached response is received and we recommend its use within your post requests this provides the ability to confirm the outcome of a request when used as a filter with our search endpoints example a post request was made to /ach/v1/payments which resulted in a 500 http response the request was then retried using the same idempotency key and request body which resulted in a cached response the next step would be to send a get request to /ach/v1/payments (for example) while using clientidentifier as a filter https //sandbox crbcos com/ach/v1/payments?clientidentifier=45654ac5 8385 4a1c 8154 b441006ab7b9 if the response returns a record then that means the original request was successful otherwise, if no record is returned then it is safe to retry the request using a new idempotency key key principles idempotency keys use the same idempotency key as the original request when retrying failures this ensures you receive a cached response if the original request was processed, allowing you to prevent duplicate operations when cached responses occur in certain scenarios involving 409 conflict and 5xx server errors , you may receive a cached response 409 conflict the response may indicate a conflict with a previous request using the same idempotency key the conflict might be due to a retry of a previously successful request (you'll receive the cached response) a genuinely conflicting request (e g , attempting to create a resource that already exists) 5xx server errors in rare cases, a server error might occur after your request was processed but before the response was sent when you retry with the same idempotency key if the original request was processed, you'll receive a cached response with the result if the original request was not processed, the retry will process your request