Trade Finance APIs - Response Code and Formats

Response Codes and Formats

HTTP Response Code Overview

The table below lists the HTTP Response Codes and descriptions

HTTP Response Code Description Message Level Encryption
200 OK The enquiry request was completed successfully. Yes
201 Created Resource created successfully. Yes
400 Bad Request Bad Request. No
401 Unauthorized Authorization credentials are missing or invalid No
403 Forbidden Access is forbidden. No
404 Not Found Empty resource/resource not found. No
409 Conflict Conflict due to duplicated Request No
422 Unprocessable Entity Request denied. Instruction is understood but not processed due to violation. No
500 Internal Server Error The request failed due to an internal error. Please contact HSBC technical support No
503 Service Unavailable The server is not ready to handle the request. (Due to server maintenance or overloaded) No

 

Error Details and troubleshooting

The table below lists the Mappings of HTTP and HSBC Response Codes and descriptions

Errors and Troubleshooting
type title status detail/ what is the error Troubleshooting Remarks
/problem-details/types/validation-errors#%paramKey001% Fields invalid 400 Key and value must not be blank. These are requestor side's errors related to invalid input of Request Header/ Query Parameters/ Unencrypted JSON Body. Please refer to corresponding API Specification and correct the errors.  
should be no longer than %maxLength% characters.  
must be %Enum1%,%Enum2%,%Enum3%.  
must be provided in format of YYYY-MM-DD and correct date time.  
must match the pattern of [0-9]{1,14}(\\.[0-9]{1,3})?.  
/authn-error/code/EDSPER1001 Unauthorized , Invalid credentials. 401 Mandatory field Kid is missing or invalid in the customer JWT header Check if the correct key ID (Client's private key) in the token. Request Header's Token Values
/authn-error/code/EDSPER1002 Invalid PGP Key , Key is set to never expiry Contact client implementation manger to re-submit a new client public key with expiration <=24 months from now
/authn-error/code/EDSPER1003 Invalid PGP Key , Key is expired  
/authn-error/code/EDSPER1004 Invalid PGP Key Check if the correct Client's Private key is used to sign the token.
/authn-error/code/EDSPER1005 Customer JWT is expired Check if "iat" in the token is generated based on current time.
/authn-error/code/EDSPER1006 Mandatory field claim "iat" is missing or invalid from customer JWT header  
/authn-error/code/EDSPER1007 Mandatory field claim  "Alg" is missing or invalid  in customer JWT header Check if the valid singature algorithm is inputted in the token.
/authn-error/code/EHVDER5010 Algorithm is  Not Supported  
/authn-error/code/EDSPER1008 Mandatory field Sub (profile id) is missing or invalid in customer JWT body Check if "sub" is inputted in the token claims.
/authn-error/code/EDSPER2002 User does not exist Check if a valid "sub" is inputted in the token claims. This value is the profile ID you received from the client implementation manager
/authn-error/code/EDSPER2003 Mandatory field jti is missing or invalid in customer JWT payload Check if a "jti" is a valid uuid
/authn-error/code/EDSPER2004 User account is locked Please wait for 5 minutes and retry.
/authn-error/code/EDSPER2005 JWT Signature validation failed / Invalid JWT Signature Check if the correct Client's Private key is used to sign the token.
/authn-error/code/EDSPER2006 Blocked access to user accessing from sanctioned country  
/authn-error/code/EDSPER2007 IP address missing so sanctioned country check failed.  
/authn-error/code/EDSPER2008 Invalid Authentication Token Check if Token is inputted in the Request Header:
Authorization: JWS {{token}}
X-HSBC-Trade-Finance-Token: JWS {{token}}
/authn-error/code/EHVDER5008
/authn-error/code/EDSPER2009 Either Client Token or Payload is in Invalid format Check if the HTTP request body format is correct. Refer to General API Request Structure
/authn-error/code/EHVDER5009
/authn-error/code/EDSPER2010 Mandatory field aud is missing or invalid in customer JWT payload Check if "aud" is inputted in the token claims as "baas".
/authn-error/code/EDSPER2012 Mandatory field ver is missing or invalid from JWT header Check if "ver" is inputted in the token headers as "1.0"
/authn-error/code/EDSPER2013 User Login credentials are invalid Please contact Client Implementation Manager
/authn-error/code/EDSPEX2014 Partner-customer relationship verification failed Check if "obo.sub" (Customer Profile ID) in the token claims is correct and entitled to access the corresponding api endpoint
/authn-error/code/EHVDER5011 Payload hash in the token claims does not match the HTTP Request Body Check if the Payload Hash is generated from the HTTP Request Body.
/problem-details/types/customer-info-invalid Customer info invalid 403 AuthZ check failed, please check your customer info Check if valid ""sub"", ""obo.sub"" in the token claims is inputted along with a valid auth-z identifier.
The Auth-z identifier varies for different API. Please refer to the corresponding specification.

The auth-z identifier for different product:

Bank Guarantee: tradeAccounts

Receivables Finance: sellerId

Point of Sale Finance: sellerId

Buyer Loans: tradeAccounts

Seller Loans: tradeAccounts

TradePay: tradeAccounts

Supply Chain Finance:buyerCode

Import Letters of Credit: tradeAccounts

Import Collection: tradeAccounts

Export Letters of Credit: tradeAccounts

Export Collection: tradeAccounts
/problem-details/types/data-not-found data not found 404 data not found Try to widen the search criteria (Query Parameters in the Get Request)  
/problem-details/types/incorrect-idempotency-key Header Required Field Incorrect 409 Duplicated X-HSBC-Request-Idempotency-Key: #%idempontencyKeyValue% Check if the request has already been sent. For a new request, use a new uuid.  
PAYLOAD-INCORRECT Request Payload Incorrect 422 Provided Key id does not match the key client used on this payload Check if the correct bank public key is used to encrypt the request.  
/problem-details/types/internal-server-error Internal Server Error 500 Internal Server Error - This includes uncategorized Exceptions Contact Client Implementation Manager  
/problem-details/types/bad-gateway Bad Gateway 502 Bank System Outage Retry in a while. Contact Technical Support if Problem persist.  
/problem-details/types/service-unavailable Service Unavailable 503  
/problem-details/types/gateway-timeout Gateway Timeout 504  

Return to top

© HSBC Bank plc 2024