HTTP codes and request error handling
- 13 Sep 2024
- 3 Minutes to read
- Print
- DarkLight
HTTP codes and request error handling
- Updated on 13 Sep 2024
- 3 Minutes to read
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
When you send a request to the Payments Hub API, you receive an HTTP code as part of the response. This response code lets you know whether your request has been successful or has failed. This document explains the different HTTP response codes that Payments Hub sends, and how you can react to error situations.
Successful response codes
Payments Hub uses the 200 and 201 response codes to indicate a successful request. The following table describes what these codes mean when received in response to a POST or GET request.
Table: Success response codes.
HTTP code | Description | Cause | |
|---|---|---|---|
POST request | GET request | ||
200 | OK | Successful, but the operation is idempotent, and the same request was submitted successfully previously. This means that no new payment is created, and the previous request relating to the payment is unchanged. | Requested details were successfully retrieved |
201 | Created | New payment was successfully created | N/A |
Client error response codes
Payments Hub returns error codes in the 4XX range when there is a client-side error. The following table lists the possible client-side errors that you can receive from Payments Hub.
Table: Client-side error response codes.
HTTP code | Description | Cause |
|---|---|---|
400 | Bad request | Payments Hub could not understand the request message. Check that you are not missing any parameters in your request header and that your request body is valid. |
401 | Unauthorized | There is an authentication error. Check that your access token and any JSON Web Token (JWT) Bearer tokens are valid. |
403 | Forbidden | You are not authorized to access the requested Payments Hub information. |
404 | Not found | he message you are trying to retrieve does not exist. For a GET request, check that the Payments Hub ID is correct, and for both GET and POST requests, make sure that you are sending the request to the correct API endpoint. |
415 | Unsupported media type | Payments Hub cannot accept the request due to an unsupported format in the request header or body. Check that your request header and body are in the correct format. |
Server error response codes
Payments Hub returns error codes in the 5XX range when there is a server-side error. The following table lists the possible server-side errors that you can receive from Payments Hub.
Table: Server-side error response codes.
HTTP code | Description | Cause |
|---|---|---|
500 | Internal server error | Payments Hub encountered an error when processing your request |
502 | Bad gateway | Payments Hub encountered network issues with its connection to a different server needed to process your request |
503 | Service unavailable | Payments Hub could not process the request. This can be due to the server being down for maintenance or temporarily offline. |
504 | Gateway timeout | Payments Hub did not receive a timely response from a different server needed to process your request |
Handling error situations
If you receive a client- or server-side error response code from Payments Hub, use the following guidelines to attempt to solve the problem and resend your request.
Note
Never simply assume that Payments Hub has not processed a request when an error response code is received. If you receive an error for a POST request, you can either send a GET request to check if the payment was processed by Payments Hub, or resend the original POST request and see if a 200 response code is returned, meaning that the original request was processed.
The authentication endpoint can be used to perform a health check for the Payments Hub API, allowing you to determine whether there are ongoing issues with the system.
For client-side error response codes:
Verify that your credentials are correct and that you are sending the request to the correct API endpoint.
Verify that your request format is valid and that the request contains all the mandatory elements.
If you are still receiving client-side error response codes, contact Payments Hub support.
For server-side error response codes:
During the first 1 minute, resend your request every 5 seconds or until you receive a 200 or 201 response code.
If the problem persists, during the next hour, resend your request every 60 seconds or until you receive a 200 or 201 response code.
If you are still receiving server-side error response codes after 1 hour, contact Payments Hub support.
Note
To avoid duplication of payments, make sure that the exact same ISO20022 message is resent in the request body on each retry. Do not amend any of the fields in the ISO20022 payload.
Was this article helpful?
